talon-agent 5.18.2 → 5.19.1

package/src/frontend/telegram/actions/index.ts

@@ -24,6 +24,8 @@ import { mediaHandlers } from "./media.js";
 import { chatInfoHandlers } from "./chat-info.js";
 import { moderationHandlers } from "./moderation/index.js";
 import type { TelegramActionContext, TelegramActionHandlers } from "./types.js";
+import { trackDeliveries } from "../../health/delivery.js";
+import { telegramDelivery } from "./send.js";
 
 export { sendText } from "./send.js";
 
@@ -58,7 +60,7 @@ export function createTelegramActionHandler(
   // shutdown — the timers died with the process, the store didn't.
   restoreScheduledMessages(bot, ctx.scheduledMessages);
 
-  return async (
+  const dispatch = async (
     body: Record<string, unknown>,
     chatId: number,
   ): Promise<ActionResult | null> => {
@@ -67,4 +69,5 @@ export function createTelegramActionHandler(
     if (!handler) return null; // not a Telegram action
     return handler(body, chatId, ctx);
   };
+  return trackDeliveries(telegramDelivery, dispatch);
 }

package/src/frontend/telegram/actions/send.ts

@@ -14,8 +14,16 @@ import {
   noteRichMessageFailure,
   richMessagesAvailable,
 } from "./rich-messages.js";
+import { createDeliveryTracker } from "../../health/delivery.js";
 import { recordOutgoingText } from "./outgoing-log.js";
 
+/** Reply delivery streaks — shared by the reply actions and text blocks. */
+export const telegramDelivery = createDeliveryTracker(
+  "telegram",
+  "Telegram",
+  "bot",
+);
+
 export function replyParams(
   body: Record<string, unknown>,
 ): ReplyParams | undefined {

package/src/frontend/telegram/handlers/context.ts

@@ -147,17 +147,28 @@ export function getForwardContext(msg: {
   return `[Forwarded from ${from}]\n`;
 }
 
+/**
+ * Deadline for one whole download (getFile + body). Media handlers run in
+ * grammY's update loop, which handles updates one at a time, so a download
+ * stalled on a dead socket holds every later message behind it.
+ */
+const DOWNLOAD_TIMEOUT_MS = 120_000;
+
 export async function downloadTelegramFile(
   bot: Bot,
   config: TalonConfig,
   fileId: string,
   fileName: string,
 ): Promise<string> {
-  const file = await bot.api.getFile(fileId);
+  const signal = AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS);
+  const file = await bot.api.getFile(
+    fileId,
+    signal as Parameters<Bot["api"]["getFile"]>[1],
+  );
   if (!file.file_path) throw new Error("Could not get file path from Telegram");
 
   const url = `https://api.telegram.org/file/bot${config.botToken}/${file.file_path}`;
-  const resp = await fetch(url);
+  const resp = await fetch(url, { signal });
   if (!resp.ok) throw new Error(`Download failed: ${resp.status}`);
 
   // Guard against excessively large files (50MB limit)

package/src/frontend/telegram/handlers/delivery.ts

@@ -10,7 +10,7 @@ import { toolInputToRecord } from "../../../core/agent-runtime/events.js";
 import { appendDailyLogResponse } from "../../../storage/daily-log.js";
 import { stripMcpPrefix } from "../../../core/tools/index.js";
 import { logWarn } from "../../../util/log.js";
-import { replyParamsFor, sendText } from "../actions/send.js";
+import { replyParamsFor, sendText, telegramDelivery } from "../actions/send.js";
 import { ambientThreadId } from "../topics.js";
 import { isAdminInGroup, trackDmUser } from "./access.js";
 
@@ -90,10 +90,7 @@ function createStreamCallbacks(
   state: StreamState,
   chatTitle?: string,
 ) {
-  const onStreamDelta = async (
-    accumulated: string,
-    _phase?: "thinking" | "text",
-  ) => {
+  const onStreamDelta = async (accumulated: string) => {
     // Skip if drafts not supported or not ready
     if (draftsSupported === false || !state.started || state.editing) return;
     if (accumulated.length - state.lastSentLength < 40) return;
@@ -122,7 +119,13 @@ function createStreamCallbacks(
   };
 
   const onTextBlock = async (text: string) => {
-    await sendText(bot, chatId, text, _replyToId);
+    try {
+      await sendText(bot, chatId, text, _replyToId);
+    } catch (err) {
+      telegramDelivery.failed(chatId, err);
+      throw err;
+    }
+    telegramDelivery.delivered(chatId);
     appendDailyLogResponse("Talon", text, { chatTitle });
     state.lastSentLength = 0;
     state.sentTextBlock = true;
@@ -223,12 +226,12 @@ export async function processAndReply(
             textAccum += event.text;
             // Fire-and-forget: draft edits are throttled + self-mutexed
             // (`state.editing`), so we must NOT block stream consumption
-            // on them — same non-awaited semantics the old bridge had.
-            void onStreamDelta(textAccum, "text");
+            // on them.
+            void onStreamDelta(textAccum);
             break;
           case "reasoning":
             thinkingAccum += event.text;
-            void onStreamDelta(thinkingAccum, "thinking");
+            void onStreamDelta(thinkingAccum);
             break;
           case "assistant_message":
             // Keep the running total monotonic so a following

package/src/frontend/telegram/handlers/index.ts

@@ -9,8 +9,6 @@
  *   - `delivery` — HTML send, streaming drafts, the agent run pipeline
  *   - `queue`    — per-chat debounce queue + per-user rate limiting
  *   - `messages` — per-message-type handlers (text/photo/voice/…/callback)
- *
- * Re-exports the same public surface the old single-file module exposed.
  */
 
 export {

package/src/frontend/telegram/index.ts

@@ -6,7 +6,7 @@
  * core gateway so MCP tool calls route to Telegram API.
  */
 
-import { Bot, InputFile, API_CONSTANTS } from "grammy";
+import { Bot, GrammyError, InputFile, API_CONSTANTS } from "grammy";
 import { autoRetry } from "@grammyjs/auto-retry";
 import { apiThrottler } from "@grammyjs/transformer-throttler";
 import {
@@ -17,6 +17,7 @@ import type { ContextManager } from "../../core/types.js";
 import type { Gateway } from "../../core/engine/gateway.js";
 import { runUntilStopped } from "../../core/frontend-runtime/run-loop.js";
 import { pollDeadline } from "./polling/poll-deadline.js";
+import { pollHealth } from "./polling/poll-health.js";
 import { createTelegramActionHandler, sendText } from "./actions/index.js";
 import { ambientThreadId } from "./topics.js";
 import { initUserClient, disconnectUserClient } from "./userbot.js";
@@ -48,6 +49,12 @@ export type TelegramFrontend = {
   stop: () => Promise<void>;
 };
 
+/** The slice of a grammY BotError's context the error log reads. */
+type UpdateContext = {
+  update?: { update_id?: number };
+  chat?: { id?: number };
+};
+
 // ── Access ──────────────────────────────────────────────────────────────────
 
 /**
@@ -68,6 +75,30 @@ function applyAccessControl(config: TalonConfig): void {
   setAllowedGroups(config.allowedGroups);
 }
 
+/**
+ * The bot's last-resort middleware error handler: log which update in which
+ * chat failed, and exit when Telegram says the token itself is bad.
+ */
+function onBotError(err: unknown): void {
+  const ctx = (err as { ctx?: UpdateContext } | null)?.ctx;
+  logError(
+    "bot",
+    `Unhandled bot error update=${ctx?.update?.update_id ?? "?"} chat=${ctx?.chat?.id ?? "?"}`,
+    err,
+  );
+  // Judge the token by Telegram's error code, never the message text:
+  // a handler's ordinary 400 ("message to edit not found", "chat not
+  // found") must not take the whole daemon down.
+  const cause = (err as { error?: unknown } | null)?.error ?? err;
+  if (
+    cause instanceof GrammyError &&
+    (cause.error_code === 401 || cause.error_code === 404)
+  ) {
+    logError("bot", "Bot token appears invalid — shutting down");
+    process.exit(1);
+  }
+}
+
 // ── Factory ─────────────────────────────────────────────────────────────────
 
 export function createTelegramFrontend(
@@ -80,6 +111,8 @@ export function createTelegramFrontend(
   bot.api.config.use(pollDeadline());
   bot.api.config.use(apiThrottler());
   bot.api.config.use(autoRetry({ maxRetryAttempts: 3, maxDelaySeconds: 60 }));
+  // Outermost: judges each poll by the result grammY finally sees.
+  bot.api.config.use(pollHealth());
 
   const context: ContextManager = {
     acquire: (chatId: number, stringId?: string) =>
@@ -149,14 +182,7 @@ export function createTelegramFrontend(
     },
 
     async start() {
-      bot.catch((err: unknown) => {
-        const msg = err instanceof Error ? err.message : String(err);
-        logError("bot", "Unhandled bot error", err);
-        if (/unauthorized|401|not found|404/i.test(msg)) {
-          logError("bot", "Bot token appears invalid — shutting down");
-          process.exit(1);
-        }
-      });
+      bot.catch(onBotError);
       // Beyond grammY's defaults: `chat_join_request` feeds the moderation
       // tool's pending-join cache (inert unless the bot admins an
       // approval-gated chat).

package/src/frontend/telegram/polling/poll-health.ts

@@ -0,0 +1,110 @@
+/**
+ * Long-poll health — the operator hears when the bot stops receiving.
+ *
+ * grammY retries a failed getUpdates forever (3s apart, or Telegram's
+ * `retry_after`) and logs nothing outside its debug channel, so a bot cut
+ * off from api.telegram.org used to look exactly like a quiet day. This
+ * transformer watches every getUpdates grammY makes:
+ *
+ *   - each failure is logged with its attempt number, the time down so far,
+ *     grammY's backoff and the error; failures that persist for
+ *     `POLL_OUTAGE_MS` raise `telegram.polling`, and the next successful
+ *     poll resolves it;
+ *   - 409 Conflict (another process polling the same token) and 401 (token
+ *     rejected) end grammY's polling loop outright, so they alert at once
+ *     and critically — nothing will retry them.
+ *
+ * Installed outermost, so it sees what grammY sees: one result per poll,
+ * after the deadline and auto-retry layers have had their turn.
+ */
+
+import { GrammyError, type Transformer } from "grammy";
+import {
+  raiseAlert,
+  resolveAlert,
+} from "../../../core/frontend-runtime/alerts.js";
+import { log, logError, logWarn } from "../../../util/log.js";
+import { createOutage, errorText } from "../../health/outage.js";
+
+/** Failed polls must persist this long before `telegram.polling` fires. */
+const POLL_OUTAGE_MS = 5 * 60_000;
+/** grammY's pause between failed getUpdates calls (bot.js handlePollingError). */
+const GRAMMY_RETRY_MS = 3_000;
+
+function backoffMs(err: unknown): number {
+  if (err instanceof GrammyError && err.error_code === 429) {
+    return (err.parameters.retry_after ?? 3) * 1000;
+  }
+  return GRAMMY_RETRY_MS;
+}
+
+export function pollHealth(thresholdMs = POLL_OUTAGE_MS): Transformer {
+  const outage = createOutage({
+    key: "telegram.polling",
+    thresholdMs,
+    describe: (err, mins) =>
+      `Telegram polling has failed for ${mins} min: ${err}. Messages are not being received.`,
+    recovered: "Telegram polling is working again.",
+  });
+  let conflict = false;
+
+  const onFatal = (err: GrammyError): void => {
+    const detail = errorText(err);
+    logError(
+      "bot",
+      `telegram.poll.stopped code=${err.error_code} err=${detail}`,
+    );
+    if (err.error_code === 409) {
+      conflict = true;
+      raiseAlert(
+        "telegram.conflict",
+        `Another process is polling this Telegram bot token (${detail}). ` +
+          "Talon has stopped receiving Telegram messages: stop the other instance, then restart Talon.",
+        { severity: "critical" },
+      );
+    } else {
+      outage.raiseNow(
+        `Telegram rejected the bot token (${detail}). Talon has stopped receiving Telegram messages.`,
+        "critical",
+      );
+    }
+  };
+
+  return async (prev, method, payload, signal) => {
+    if (method !== "getUpdates") return prev(method, payload, signal);
+    try {
+      const res = await prev(method, payload, signal);
+      const ended = outage.ok();
+      if (ended) {
+        log(
+          "bot",
+          `telegram.poll.recovered failed_attempts=${ended.attempts} down_ms=${ended.downMs}`,
+        );
+      }
+      if (conflict) {
+        conflict = false;
+        resolveAlert(
+          "telegram.conflict",
+          "Telegram polling resumed — no other process is polling this bot token.",
+        );
+      }
+      return res;
+    } catch (err) {
+      // bot.stop() cancelling the in-flight poll is a shutdown, not a fault.
+      if (signal?.aborted) throw err;
+      if (
+        err instanceof GrammyError &&
+        (err.error_code === 409 || err.error_code === 401)
+      ) {
+        onFatal(err);
+        throw err;
+      }
+      const { attempt, downMs } = outage.fail(err);
+      logWarn(
+        "bot",
+        `telegram.poll.fail attempt=${attempt} down_ms=${downMs} backoff_ms=${backoffMs(err)} err=${errorText(err)}`,
+      );
+      throw err;
+    }
+  };
+}

package/src/frontend/telegram/userbot.ts

@@ -17,6 +17,7 @@ import writeFileAtomic from "write-file-atomic";
 import { log, logError, logWarn } from "../../util/log.js";
 import { dirs, files } from "../../util/paths.js";
 import { formatSmartTimestamp } from "../../util/time.js";
+import { createOutage, errorText } from "../health/outage.js";
 
 const SESSION_FILE = files.userSession;
 
@@ -152,6 +153,39 @@ export function withTimeout<T>(
   return Promise.race([p, timeout]).finally(() => clearTimeout(timer));
 }
 
+/** How long the monitor may fail to reconnect before the operator hears. */
+const USERBOT_OUTAGE_MS = 15 * 60 * 1000;
+
+const outage = createOutage({
+  key: "telegram.userbot",
+  thresholdMs: USERBOT_OUTAGE_MS,
+  severity: "warn",
+  describe: (err, mins) =>
+    `The Telegram user client has failed to reconnect for ${mins} min: ${err}. ` +
+    "Full history search and member lookups are unavailable.",
+  recovered: "The Telegram user client is reconnected.",
+});
+
+/** One failed monitor step, logged with its place in the outage. */
+function noteFailure(step: string, err: unknown): void {
+  const { attempt, downMs } = outage.fail(err);
+  logWarn(
+    "userbot",
+    `userbot.reconnect.fail step=${step} attempt=${attempt} down_ms=${downMs} ` +
+      `next_check_ms=${CHECK_INTERVAL_MS} err=${errorText(err)}`,
+  );
+}
+
+/** A healthy monitor step; logs the end of an outage when there was one. */
+function noteHealthy(via: string): void {
+  const ended = outage.ok();
+  if (!ended) return;
+  log(
+    "userbot",
+    `userbot.reconnect.ok via=${via} failed_attempts=${ended.attempts} down_ms=${ended.downMs}`,
+  );
+}
+
 let reconnecting = false;
 // Bumped by stopConnectionMonitor so a tick whose awaits straddle a shutdown
 // can tell that its own client was torn down under it — the liveness probe
@@ -164,8 +198,19 @@ function startConnectionMonitor(): void {
   const gen = monitorGeneration;
   reconnectTimer = setInterval(async () => {
     if (gen !== monitorGeneration) return;
-    if (!client) return;
     if (reconnecting) return; // prevent overlapping reconnect attempts
+    if (!client) {
+      // A failed re-init leaves no client. Retry it every tick; bailing
+      // here left the userbot dead until the daemon restarted.
+      if (!storedApiId || !storedApiHash) return;
+      reconnecting = true;
+      try {
+        await reinitClient();
+      } finally {
+        reconnecting = false;
+      }
+      return;
+    }
 
     // GramJS keeps `client.connected === true` even after the underlying
     // socket has silently died, so a real round-trip is the only reliable
@@ -179,6 +224,7 @@ function startConnectionMonitor(): void {
           RECONNECT_STEP_TIMEOUT_MS,
           "liveness probe",
         );
+        noteHealthy("probe");
         return; // genuinely alive
       } catch {
         if (gen !== monitorGeneration) return; // monitor stopped mid-probe
@@ -203,55 +249,73 @@ function startConnectionMonitor(): void {
         )
       ) {
         log("userbot", "Reconnected successfully.");
+        noteHealthy("reconnect");
       } else {
         logWarn("userbot", "Reconnected but not authorized.");
+        noteFailure("reconnect", "connected but not authorized");
       }
     } catch (err) {
       if (gen !== monitorGeneration) return; // stopped while reconnecting
       logError("userbot", "Reconnect failed", err);
-      // Try a full re-init on next check
-      if (storedApiId && storedApiHash) {
-        try {
-          // Drop the wedged client without awaiting it — its socket may be
-          // the thing that's hung.
-          const stale = client;
-          client = null;
-          void stale?.disconnect().catch(() => {});
-          let sessionString = "";
-          if (existsSync(SESSION_FILE)) {
-            sessionString = readFileSync(SESSION_FILE, "utf-8").trim();
-          }
-          const session = new StringSession(sessionString);
-          client = new TelegramClient(session, storedApiId, storedApiHash, {
-            connectionRetries: 5,
-          });
-          await withTimeout(
-            client.connect(),
-            RECONNECT_STEP_TIMEOUT_MS,
-            "re-init connect",
-          );
-          if (
-            await withTimeout(
-              client.isUserAuthorized(),
-              RECONNECT_STEP_TIMEOUT_MS,
-              "re-init auth check",
-            )
-          ) {
-            log("userbot", "Full re-init reconnect succeeded.");
-          }
-        } catch (retryErr) {
-          logError("userbot", "Full re-init reconnect failed", retryErr);
-          client = null;
-        }
-      }
+      if (storedApiId && storedApiHash) await reinitClient();
+      else noteFailure("reconnect", err);
     } finally {
       reconnecting = false;
     }
   }, CHECK_INTERVAL_MS);
 }
 
+/**
+ * Replace the client with a fresh one from the saved session. On failure
+ * the slot is left empty (and the failed client closed); the monitor's
+ * next tick tries again.
+ */
+async function reinitClient(): Promise<void> {
+  // Drop the wedged client without awaiting it — its socket may be the
+  // thing that's hung.
+  const stale = client;
+  client = null;
+  void stale?.disconnect().catch(() => {});
+  let fresh: TelegramClient | null = null;
+  try {
+    let sessionString = "";
+    if (existsSync(SESSION_FILE)) {
+      sessionString = readFileSync(SESSION_FILE, "utf-8").trim();
+    }
+    const session = new StringSession(sessionString);
+    fresh = new TelegramClient(session, storedApiId, storedApiHash, {
+      connectionRetries: 5,
+    });
+    client = fresh;
+    await withTimeout(
+      fresh.connect(),
+      RECONNECT_STEP_TIMEOUT_MS,
+      "re-init connect",
+    );
+    if (
+      await withTimeout(
+        fresh.isUserAuthorized(),
+        RECONNECT_STEP_TIMEOUT_MS,
+        "re-init auth check",
+      )
+    ) {
+      log("userbot", "Full re-init reconnect succeeded.");
+      noteHealthy("re-init");
+    } else {
+      noteFailure("re-init", "connected but not authorized");
+    }
+  } catch (retryErr) {
+    logError("userbot", "Full re-init reconnect failed", retryErr);
+    noteFailure("re-init", retryErr);
+    if (client === fresh) client = null;
+    // Its connect may still be retrying in the background.
+    void fresh?.disconnect().catch(() => {});
+  }
+}
+
 function stopConnectionMonitor(): void {
   monitorGeneration++;
+  outage.dispose();
   if (reconnectTimer) {
     clearInterval(reconnectTimer);
     reconnectTimer = null;

package/src/frontend/terminal/builtins/session.ts

@@ -1,7 +1,7 @@
 /** `/reset`, `/resume`, `/rename` — session lifecycle. */
 
 import pc from "picocolors";
-import { formatTimeAgo } from "../renderer.js";
+import { formatRelativeAge } from "../../../util/time.js";
 import { isTerminalChatId } from "../../../core/frontend-runtime/chat-id.js";
 import { resolveModel as coreResolveModel } from "../../../core/models/catalog.js";
 import {
@@ -49,7 +49,7 @@ export const resumeCommand: Command = {
         ? `"${s.info.sessionName}"`
         : pc.dim("(unnamed)");
       const turns = `${s.info.turns} turn${s.info.turns !== 1 ? "s" : ""}`;
-      const ago = formatTimeAgo(s.info.lastActive);
+      const ago = formatRelativeAge(s.info.lastActive);
       const model = s.info.lastModel
         ? (coreResolveModel(s.info.lastModel)?.displayName ?? s.info.lastModel)
         : "";

package/src/frontend/terminal/index.ts

@@ -8,9 +8,7 @@
  *   - Renderer NEVER touches readline. Only this file does.
  *
  * `start()` returns once that prompt is drawn — the frontend lifecycle
- * contract (core/frontend-runtime/capabilities.ts). It used to park on a
- * promise that never resolved, which is why the composition root had to
- * special-case the terminal and start it without awaiting.
+ * contract (core/frontend-runtime/capabilities.ts).
  */
 
 import pc from "picocolors";

package/src/frontend/terminal/renderer.ts

@@ -7,7 +7,7 @@
  */
 
 import pc from "picocolors";
-import { formatUsd } from "../presentation/format.js";
+import { formatTokenCount, formatUsd } from "../presentation/format.js";
 
 // ── Types ────────────────────────────────────────────────────────────────────
 
@@ -70,22 +70,6 @@ export function wrap(text: string, indent: number, maxWidth: number): string {
     .join("\n");
 }
 
-export function formatTimeAgo(ts: number): string {
-  const sec = Math.floor((Date.now() - ts) / 1000);
-  if (sec < 60) return "just now";
-  const min = Math.floor(sec / 60);
-  if (min < 60) return `${min}m ago`;
-  const hr = Math.floor(min / 60);
-  if (hr < 24) return `${hr}h ago`;
-  return `${Math.floor(hr / 24)}d ago`;
-}
-
-function fmtTok(n: number): string {
-  if (n < 1000) return String(n);
-  if (n < 1_000_000) return `${(n / 1000).toFixed(1)}k`;
-  return `${(n / 1_000_000).toFixed(1)}M`;
-}
-
 export function extractToolDetail(
   input: Record<string, unknown>,
   maxLen: number,
@@ -189,7 +173,7 @@ export function createRenderer(cols?: number, displayName = "Talon"): Renderer {
     if (info.sessionName) p.push(`"${info.sessionName}"`);
     p.push(
       `${info.turns} turn${info.turns !== 1 ? "s" : ""}`,
-      `${fmtTok(info.inputTokens + info.outputTokens)} tok`,
+      `${formatTokenCount(info.inputTokens + info.outputTokens)} tok`,
     );
     if (typeof info.cacheHitPct === "number") {
       p.push(`${info.cacheHitPct}% cache`);

package/src/frontend/whatsapp/actions/index.ts

@@ -33,6 +33,16 @@ import { mediaHandlers } from "./media.js";
 import { messagingHandlers } from "./messaging.js";
 import { moderationHandlers } from "./moderation.js";
 import type { WhatsAppActionContext, WhatsAppActionHandlers } from "./types.js";
+import {
+  createDeliveryTracker,
+  trackDeliveries,
+} from "../../health/delivery.js";
+
+const delivery = createDeliveryTracker("whatsapp", "WhatsApp", "whatsapp");
+
+/** A cross-send names its destination; everything else goes to `chatId`. */
+const destination = (body: Record<string, unknown>, chatId: number) =>
+  body.target !== undefined ? String(body.target) : chatId;
 
 // Null-prototype so a request `action` of "toString" / "constructor" can't
 // resolve an inherited Object.prototype method via `handlers[action]`.
@@ -62,7 +72,7 @@ export function createWhatsAppActionHandler(
 ) {
   const scheduledMessages = new Map<string, ReturnType<typeof setTimeout>>();
 
-  return async (
+  const dispatch = async (
     body: Record<string, unknown>,
     chatId: number,
   ): Promise<ActionResult | null> => {
@@ -118,4 +128,5 @@ export function createWhatsAppActionHandler(
       ? { ...result, chat_id: chat.chatId }
       : result;
   };
+  return trackDeliveries(delivery, dispatch, destination);
 }

package/src/frontend/whatsapp/actions/messaging.ts

@@ -17,6 +17,9 @@ import { tryAction } from "./try-action.js";
 import { resolveQuoted, sendContent, sendText, boundedSend } from "./send.js";
 import type { WhatsAppActionHandlers } from "./types.js";
 
+/** The tool schema's documented ceiling (1-86400), as telegram/discord clamp. */
+const MAX_DELAY_SEC = 24 * 60 * 60;
+
 /** WhatsApp keeps a pin for 24h, 7d, or 30d — no indefinite option. */
 const PIN_DURATIONS = [86_400, 604_800, 2_592_000] as const;
 
@@ -229,16 +232,18 @@ export const messagingHandlers: WhatsAppActionHandlers = {
   schedule_message: (body, _chatId, ctx) =>
     tryAction("schedule_message", async () => {
       const text = String(body.text ?? "");
-      const seconds = Number(body.delay_seconds ?? 0);
+      const requested = Number(body.delay_seconds ?? 0);
       if (!text.trim()) {
         return { ok: false, error: "schedule_message: text is required" };
       }
-      if (!Number.isFinite(seconds) || seconds <= 0) {
+      if (!Number.isFinite(requested) || requested <= 0) {
         return {
           ok: false,
           error: "schedule_message: delay_seconds must be a positive number",
         };
       }
+      // Past setTimeout's 2^31-1 ms (~24.8 days) the timer fires at once.
+      const seconds = Math.min(MAX_DELAY_SEC, requested);
       const id = randomUUID();
       const chat = ctx.chat!;
       const timer = setTimeout(() => {