talon-agent 3.24.0 → 3.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "3.24.0",
+  "version": "3.25.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",
@@ -110,6 +110,7 @@
     "@opencode-ai/sdk": "^1.17.4",
     "@playwright/mcp": "0.0.79",
     "@types/cross-spawn": "^6.0.6",
+    "baileys": "^7.0.0-rc14",
     "big-integer": "^1.6.52",
     "cheerio": "^1.2.0",
     "croner": "^10.0.1",
@@ -125,6 +126,7 @@
     "picocolors": "^1.1.1",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
+    "qrcode-terminal": "^0.12.0",
     "telegram": "^2.26.22",
     "tsx": "^4.21.0",
     "undici": "^8.0.2",
@@ -135,6 +137,7 @@
   },
   "devDependencies": {
     "@types/node": "^26.0.0",
+    "@types/qrcode-terminal": "^0.12.2",
     "@types/write-file-atomic": "^4.0.3",
     "@vitest/coverage-v8": "^4.1.3",
     "dependency-cruiser": "^18.1.0",

package/prompts/whatsapp.md

@@ -0,0 +1,58 @@
+## WhatsApp Mode
+
+You are running on a personal WhatsApp account (multi-device link).
+Messages arrive as `[SenderName] msg_id:<id>: text`. Use names naturally,
+and use that `msg_id` when a tool asks for a message id — reactions,
+replies, edits, deletes and pins all address messages that way.
+
+How replies are delivered (end_turn / send_message and what counts as a
+valid turn) is defined in the **Response flow** section at the end of
+these instructions — that contract wins over anything here.
+
+### Formatting
+
+WhatsApp has its own markup, and Talon converts standard Markdown into it
+for you. Write normal Markdown; these are the shapes that survive:
+
+- `**bold**` → _bold_, `_italic_`, `~~strike~~` → ~~strike~~
+- `` `inline code` `` and fenced code blocks
+- Bullet and numbered lists, block quotes
+- Headings become bold lines — WhatsApp has no heading sizes
+- Links render as `label (https://url)`; bare URLs auto-link
+- Tables become an aligned monospace block; keep them narrow
+
+Long messages are split across bubbles automatically at 4096 characters.
+
+### What works here
+
+Text, replies, reactions, edits, deletes, forwards, pins, and typing
+indicators. Media: photos, video, GIFs, voice notes, audio, documents,
+stickers (.webp), round video notes, and albums. Also polls, locations,
+venues, and contact cards. In groups you can read metadata, list members
+and admins, change the subject and description, manage invite links,
+handle join requests, and add/remove/promote/demote members when you are
+an admin.
+
+Inbound media is downloaded to the workspace before your turn starts —
+the file path is in the message, so you can read it immediately.
+
+### What WhatsApp cannot do
+
+- No interactive buttons on a personal account — button rows are rendered
+  as a numbered list, and people reply with the number.
+- No ban list: removing someone from a group is the only eviction, and
+  they can rejoin with an invite link.
+- No per-member mute — a group is either open or admins-only.
+- No forum topics, no custom admin titles, no stopping a poll.
+- Pins expire (24h, 7d, or 30d) and only pins Talon placed are listable.
+
+### Staying silent
+
+Reactions work here, so a react is the light acknowledgement when a
+message needs no reply; otherwise close the turn silently as the contract
+describes.
+
+### Style
+
+Concise. This is a phone chat — short paragraphs, no filler, no walls of
+text. Match the sender's register.

package/src/backend/shared/delivery-contract.ts

@@ -67,6 +67,7 @@ const FRONTEND_TOOLS: Record<string, DeliveryToolNames> = {
   discord: { endTurn: "end_turn", send: "send", react: "react" },
   teams: { endTurn: "end_turn", send: "send_message" },
   native: { endTurn: "end_turn", send: "send_message", react: "react" },
+  whatsapp: { endTurn: "end_turn", send: "send_message" },
 };
 
 const DEFAULT_TOOLS: DeliveryToolNames = {

package/src/core/doctor.ts

@@ -73,6 +73,7 @@ export interface DoctorConfigSlice {
   botToken?: string;
   teamsWebhookUrl?: string;
   discord?: { botToken?: string };
+  whatsapp?: object;
   claudeBinary?: string;
   codexApiKey?: string;
   openaiApiKey?: string;
@@ -128,6 +129,10 @@ function unconfiguredFrontends(config: DoctorConfigSlice): string[] {
     if (fe === "telegram") return !config.botToken;
     if (fe === "teams") return !config.teamsWebhookUrl;
     if (fe === "discord") return !config.discord?.botToken;
+    // WhatsApp needs no stored credential — pairing is interactive (QR /
+    // pairing code at first start) — but the config block must exist so
+    // the JID allowlists were consciously set.
+    if (fe === "whatsapp") return !config.whatsapp;
     return fe !== "terminal" && fe !== "native";
   });
 }

package/src/core/frontend-runtime/builtins.ts

@@ -24,6 +24,7 @@ import {
   isTeamsChatId,
   isTelegramChatId,
   isTerminalChatId,
+  isWhatsAppChatId,
 } from "../../util/chat-id.js";
 
 function registerBuiltinFrontends(): void {
@@ -56,6 +57,13 @@ function registerBuiltinFrontends(): void {
     routePriority: 40,
     messaging: true,
   });
+  registerFrontend({
+    id: "whatsapp",
+    label: "WhatsApp",
+    ownsChatId: isWhatsAppChatId,
+    routePriority: 50,
+    messaging: true,
+  });
   registerFrontend({
     id: "telegram",
     label: "Telegram",

package/src/core/mcp-hub/talon-server.ts

@@ -25,6 +25,7 @@ export const VALID_TOOL_FRONTENDS: ReadonlySet<string> = new Set([
   "terminal",
   "discord",
   "native",
+  "whatsapp",
 ]);
 
 export type TalonServerOptions = {

package/src/core/prompt/embedded-prompts.ts

@@ -35,6 +35,7 @@ import asset21 from "../../../prompts/system/workspace.md" with { type: "file" }
 import asset22 from "../../../prompts/teams.md" with { type: "file" };
 import asset23 from "../../../prompts/telegram.md" with { type: "file" };
 import asset24 from "../../../prompts/terminal.md" with { type: "file" };
+import asset25 from "../../../prompts/whatsapp.md" with { type: "file" };
 
 /** rel path (posix, under prompts/) → embedded file path (/$bunfs/… when compiled). */
 const ASSETS: Record<string, string> = {
@@ -63,6 +64,7 @@ const ASSETS: Record<string, string> = {
   "teams.md": asset22,
   "telegram.md": asset23,
   "terminal.md": asset24,
+  "whatsapp.md": asset25,
 };
 
 /** Read an embedded prompt by its rel path (e.g. "system/cron.md"). */

package/src/core/tools/chat.ts

@@ -19,7 +19,7 @@ export const chatTools: ToolDefinition[] = [
     description: "List chat administrators.",
     schema: {},
     execute: (_params, bridge) => bridge("get_chat_admins", {}),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "chat",
   },
 
@@ -28,7 +28,7 @@ export const chatTools: ToolDefinition[] = [
     description: "Get total member count.",
     schema: {},
     execute: (_params, bridge) => bridge("get_chat_member_count", {}),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "chat",
   },
 
@@ -37,7 +37,7 @@ export const chatTools: ToolDefinition[] = [
     description: "Change chat title (admin).",
     schema: { title: z.string() },
     execute: (params, bridge) => bridge("set_chat_title", params),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "chat",
   },
 
@@ -46,7 +46,7 @@ export const chatTools: ToolDefinition[] = [
     description: "Change chat description (admin).",
     schema: { description: z.string() },
     execute: (params, bridge) => bridge("set_chat_description", params),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "chat",
   },
 ];

package/src/core/tools/history.ts

@@ -30,7 +30,7 @@ export const historyTools: ToolDefinition[] = [
         before: params.before,
         offset_id: params.offset_id,
       }),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "history",
   },
 
@@ -42,7 +42,7 @@ export const historyTools: ToolDefinition[] = [
       limit: z.number().optional(),
     },
     execute: (params, bridge) => bridge("search_history", params),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "history",
   },
 
@@ -54,7 +54,7 @@ export const historyTools: ToolDefinition[] = [
       limit: z.number().optional(),
     },
     execute: (params, bridge) => bridge("get_user_messages", params),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "history",
   },
 
@@ -63,7 +63,7 @@ export const historyTools: ToolDefinition[] = [
     description: "Get a specific message by ID.",
     schema: { message_id: snowflakeOrIdSchema },
     execute: (params, bridge) => bridge("get_message_by_id", params),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "history",
   },
 
@@ -77,7 +77,7 @@ export const historyTools: ToolDefinition[] = [
       ),
     },
     execute: (params, bridge) => bridge("download_media", params),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "history",
   },
 ];

package/src/core/tools/media.ts

@@ -17,7 +17,7 @@ export const mediaTools: ToolDefinition[] = [
         .describe("Number of entries (default 10, max 20)"),
     },
     execute: (params, bridge) => bridge("list_media", { limit: params.limit }),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "media",
   },
 ];

package/src/core/tools/members.ts

@@ -13,7 +13,7 @@ export const memberTools: ToolDefinition[] = [
     schema: { limit: z.number().optional() },
     execute: (params, bridge) =>
       bridge("list_known_users", { limit: params.limit }),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "members",
   },
 
@@ -22,7 +22,7 @@ export const memberTools: ToolDefinition[] = [
     description: "Get detailed info about a user by ID.",
     schema: { user_id: snowflakeOrIdSchema },
     execute: (params, bridge) => bridge("get_member_info", params),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "members",
   },
 
@@ -32,7 +32,7 @@ export const memberTools: ToolDefinition[] = [
       "Get how many members are currently online or recently active.",
     schema: {},
     execute: (_params, bridge) => bridge("online_count", {}),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "members",
   },
 
@@ -41,7 +41,7 @@ export const memberTools: ToolDefinition[] = [
     description: "Get all pinned messages in the current chat.",
     schema: {},
     execute: (_params, bridge) => bridge("get_pinned_messages", {}),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "members",
   },
 ];

package/src/core/tools/messaging.ts

@@ -110,7 +110,7 @@ Notes:
       // src/backend/claude-sdk/options.ts:turnTerminatorHook.
       return throwIfFailed(result, "end_turn");
     },
-    frontends: ["telegram", "teams", "discord", "native"],
+    frontends: ["telegram", "teams", "discord", "native", "whatsapp"],
     tag: "messaging",
     endsTurn: true,
     delivery: true,
@@ -473,7 +473,7 @@ Examples:
           return { ok: false, error: `Unknown type: ${type}` };
       }
     },
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "messaging",
     delivery: true,
   },
@@ -490,7 +490,7 @@ Examples:
       text: z.string().describe("Message text. Supports Markdown."),
     },
     execute: (params, bridge) => bridge("send_message", params),
-    frontends: ["teams", "native"],
+    frontends: ["teams", "native", "whatsapp"],
     tag: "messaging",
     delivery: true,
   },
@@ -515,7 +515,7 @@ Example: send_message_with_buttons(text="Choose:", rows=[[{"text":"Docs","url":"
         .describe("Button rows"),
     },
     execute: (params, bridge) => bridge("send_message_with_buttons", params),
-    frontends: ["teams", "native"],
+    frontends: ["teams", "native", "whatsapp"],
     tag: "messaging",
     delivery: true,
   },
@@ -572,7 +572,7 @@ Valid emoji: 👍 👎 ❤ 🔥 🥰 👏 😁 🤔 🤯 😱 🤬 😢 🎉
       const result = await bridge("react", rest);
       return throwIfFailed(result, "react");
     },
-    frontends: ["telegram", "discord", "native"],
+    frontends: ["telegram", "discord", "native", "whatsapp"],
     tag: "messaging",
     endsTurn: true,
     delivery: true,
@@ -592,7 +592,7 @@ Valid emoji: 👍 👎 ❤ 🔥 🥰 👏 😁 🤔 🤯 😱 🤬 😢 🎉
         .describe("Edit the media caption rather than message text (Telegram)"),
     },
     execute: (params, bridge) => bridge("edit_message", params),
-    frontends: ["telegram", "discord", "native"],
+    frontends: ["telegram", "discord", "native", "whatsapp"],
     tag: "messaging",
   },
 
@@ -609,7 +609,7 @@ Valid emoji: 👍 👎 ❤ 🔥 🥰 👏 😁 🤔 🤯 😱 🤬 😢 🎉
         .describe("Bulk delete these message IDs (Telegram)"),
     },
     execute: (params, bridge) => bridge("delete_message", params),
-    frontends: ["telegram", "discord", "native"],
+    frontends: ["telegram", "discord", "native", "whatsapp"],
     tag: "messaging",
   },
 
@@ -632,7 +632,7 @@ Valid emoji: 👍 👎 ❤ 🔥 🥰 👏 😁 🤔 🤯 😱 🤬 😢 🎉
         .describe("Destination chat (default: current chat)"),
     },
     execute: (params, bridge) => bridge("forward_message", params),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "messaging",
   },
 
@@ -648,7 +648,7 @@ Valid emoji: 👍 👎 ❤ 🔥 🥰 👏 😁 🤔 🤯 😱 🤬 😢 🎉
       to_chat_id: chatIdSchema.optional(),
     },
     execute: (params, bridge) => bridge("copy_message", params),
-    frontends: ["telegram"],
+    frontends: ["telegram", "whatsapp"],
     tag: "messaging",
   },
 
@@ -658,7 +658,7 @@ Valid emoji: 👍 👎 ❤ 🔥 🥰 👏 😁 🤔 🤯 😱 🤬 😢 🎉
     description: "Pin a message.",
     schema: { message_id: snowflakeOrIdSchema },
     execute: (params, bridge) => bridge("pin_message", params),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "messaging",
   },
 
@@ -668,7 +668,7 @@ Valid emoji: 👍 👎 ❤ 🔥 🥰 👏 😁 🤔 🤯 😱 🤬 😢 🎉
     description: "Unpin a message.",
     schema: { message_id: snowflakeOrIdSchema.optional() },
     execute: (params, bridge) => bridge("unpin_message", params),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "messaging",
   },
 
@@ -681,6 +681,7 @@ Valid emoji: 👍 👎 ❤ 🔥 🥰 👏 😁 🤔 🤯 😱 🤬 😢 🎉
       message_id: idSchema.describe("Message ID of the poll to stop"),
     },
     execute: (params, bridge) => bridge("stop_poll", params),
+    // No WhatsApp equivalent: its polls run until the message is deleted.
     frontends: ["telegram"],
     tag: "messaging",
   },

package/src/core/tools/moderation.ts

@@ -112,7 +112,7 @@ Forum topics (supergroups with topics):
         .describe("Target chat ID. Omit for the current chat."),
     },
     execute: (params, bridge) => bridge("moderate", params),
-    frontends: ["telegram"],
+    frontends: ["telegram", "whatsapp"],
     tag: "moderation",
   },
 
@@ -125,7 +125,7 @@ Forum topics (supergroups with topics):
       limit: z.number().optional().describe("Max photos to return (default 5)"),
     },
     execute: (params, bridge) => bridge("get_user_profile_photos", params),
-    frontends: ["telegram"],
+    frontends: ["telegram", "whatsapp"],
     tag: "moderation",
   },
 ];

package/src/core/tools/scheduling.ts

@@ -11,7 +11,7 @@ export const schedulingTools: ToolDefinition[] = [
     description: "Cancel a scheduled message.",
     schema: { schedule_id: z.string() },
     execute: (params, bridge) => bridge("cancel_scheduled", params),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "scheduling",
   },
 
@@ -21,7 +21,7 @@ export const schedulingTools: ToolDefinition[] = [
       "List pending scheduled messages in this chat (id, seconds until send, text). Scheduled messages persist across restarts.",
     schema: {},
     execute: (_params, bridge) => bridge("list_scheduled", {}),
-    frontends: ["telegram", "discord"],
+    frontends: ["telegram", "discord", "whatsapp"],
     tag: "scheduling",
   },
 

package/src/core/tools/types.ts

@@ -9,7 +9,7 @@ import type { ZodRawShape } from "zod";
 
 /** Which frontends a tool is available on.  "all" = every frontend. */
 export type ToolFrontend =
-  "telegram" | "teams" | "terminal" | "discord" | "native" | "all";
+  "telegram" | "teams" | "terminal" | "discord" | "native" | "whatsapp" | "all";
 
 /** Domain tags for runtime filtering and grouping. */
 export type ToolTag =

package/src/frontend/factories.ts

@@ -12,4 +12,5 @@ import "./telegram/factory.js";
 import "./discord/factory.js";
 import "./teams/factory.js";
 import "./native/factory.js";
+import "./whatsapp/factory.js";
 import "./terminal/factory.js";

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

@@ -8,6 +8,7 @@
 
 import type { Bot } from "grammy";
 import { respawnSelf } from "../../../util/respawn.js";
+import { isStaleCommand } from "../stale-command.js";
 import {
   getRepoRoot,
   runSelfUpdate,
@@ -154,6 +155,10 @@ export function registerAdminCommands(
       await ctx.reply("Not authorized.");
       return;
     }
+    // A restart that predates this process is a redelivery (or an order
+    // aimed at a daemon that is already gone) — obeying it would restart
+    // us again, and again, on every boot.
+    if (isStaleCommand(ctx.message?.date, "/restart")) return;
     await ctx.reply("♻️ Restarting...");
     respawnSelf("telegram /restart");
   });
@@ -169,6 +174,8 @@ export function registerAdminCommands(
         await ctx.reply("Not authorized.");
         return;
       }
+      // Same redelivery hazard as /restart — it also ends the process.
+      if (isStaleCommand(ctx.message?.date, "/update")) return;
       const remote = config.update?.remote ?? "origin";
       const branch = config.update?.branch ?? "main";
       const sent = await ctx.reply(

package/src/frontend/telegram/index.ts

@@ -23,6 +23,7 @@ import {
 } from "./commands/index.js";
 import { setAccessControl } from "./handlers/index.js";
 import { registerMiddleware } from "./middleware.js";
+import { confirmUpdates } from "./update-offset.js";
 import { registerCallbacks } from "./callbacks/index.js";
 import { log, logError } from "../../util/log.js";
 
@@ -142,6 +143,10 @@ export function createTelegramFrontend(
     async stop() {
       try {
         await bot.stop();
+        // grammY advances the update offset on its NEXT poll, which never
+        // comes once we are shutting down — so confirm it explicitly or
+        // Telegram redelivers the command that triggered this shutdown.
+        await confirmUpdates(bot);
         log("shutdown", "Bot disconnected");
       } catch (err) {
         logError("shutdown", "Bot stop error", err);

package/src/frontend/telegram/middleware.ts

@@ -10,6 +10,7 @@ import { allowChat, revokeChat } from "./userbot.js";
 import { registerChat } from "../../core/background/pulse.js";
 import { log } from "../../util/log.js";
 import { getSenderName } from "./handlers/index.js";
+import { noteUpdateId } from "./update-offset.js";
 import { noteInboundThread } from "./topics.js";
 import { recordJoinRequest } from "./join-requests.js";
 import { newlyAddedEmojis, recordReactionToBot } from "../../core/soul/taps.js";
@@ -26,6 +27,15 @@ import {
 } from "./handlers/index.js";
 
 export function registerMiddleware(bot: Bot, config: TalonConfig): void {
+  // ── Update-offset tracking (every update, before anything else) ──────────
+  // Telegram redelivers any update whose id was never confirmed; the
+  // shutdown path confirms this one so a process-ending command can't be
+  // served twice. See update-offset.ts.
+  bot.use((ctx, next) => {
+    noteUpdateId(ctx.update.update_id);
+    return next();
+  });
+
   // ── History capture (runs for ALL messages, before handlers) ─────────────
   bot.on("message", (ctx, next) => {
     const chatId = String(ctx.chat.id);

package/src/frontend/telegram/stale-command.ts

@@ -0,0 +1,46 @@
+/**
+ * Staleness guard for process-ending commands.
+ *
+ * Second layer under `update-offset.ts`. Confirming the offset stops the
+ * redelivery that caused the restart loop, but it can't be guaranteed —
+ * the confirmation is a network call on the way out, and a SIGKILL, a
+ * crash, or a 409 from two pollers skips it entirely. Any command that
+ * ends the process is therefore also checked for age: it must be newer
+ * than this process, because a `/restart` issued before we booted has
+ * either already been served (redelivery) or refers to a daemon that is
+ * no longer running.
+ *
+ * Only self-terminating commands are gated. Ordinary messages sent while
+ * the daemon was down are real work and must still be processed.
+ */
+
+import { logWarn } from "../../util/log.js";
+
+/**
+ * Grace window for clock skew between Telegram's timestamps and ours,
+ * and for a command issued in the seconds around a boot.
+ */
+const CLOCK_SKEW_GRACE_MS = 30_000;
+
+/** When this process started — the cutoff a fresh command must beat. */
+const PROCESS_START_MS = Date.now();
+
+/**
+ * True when a command predates this process and must not be re-executed.
+ * `messageDate` is Telegram's `message.date` (seconds since epoch).
+ */
+export function isStaleCommand(
+  messageDate: number | undefined,
+  command: string,
+): boolean {
+  if (!messageDate) return false; // no timestamp — treat as live
+  const sentAtMs = messageDate * 1000;
+  if (sentAtMs >= PROCESS_START_MS - CLOCK_SKEW_GRACE_MS) return false;
+  const ageSec = Math.round((Date.now() - sentAtMs) / 1000);
+  logWarn(
+    "bot",
+    `Ignoring stale ${command} from ${ageSec}s ago — it predates this process ` +
+      `(a redelivered restart would loop the daemon).`,
+  );
+  return true;
+}

package/src/frontend/telegram/update-offset.ts

@@ -0,0 +1,58 @@
+/**
+ * Update-offset confirmation — the reason a `/restart` used to run twice.
+ *
+ * Telegram's getUpdates is at-least-once: an update stays queued until a
+ * LATER call passes `offset = update_id + 1`. grammY advances that offset
+ * on its next poll, so a command that ends the process — `/restart`,
+ * `/update` — exits before the confirmation is ever sent. Telegram then
+ * redelivers it to the successor, which restarts, which never confirms
+ * either: a boot loop that survives every restart, observed live on
+ * 2026-08-22 taking the daemon down four times in a row.
+ *
+ * The fix is to confirm explicitly before exiting. This module tracks the
+ * highest update_id seen and `confirmUpdates` acknowledges it with a
+ * zero-timeout getUpdates, which is exactly what grammY's next poll would
+ * have done.
+ */
+
+import type { Bot } from "grammy";
+import { log, logWarn } from "../../util/log.js";
+
+let highestUpdateId = 0;
+
+/** Record an update as seen. Called for every update grammY dispatches. */
+export function noteUpdateId(updateId: number): void {
+  if (updateId > highestUpdateId) highestUpdateId = updateId;
+}
+
+/** Highest update id seen this process (0 when none). Test seam. */
+export function lastUpdateId(): number {
+  return highestUpdateId;
+}
+
+/** Test seam: forget the tracked offset. */
+export function resetUpdateOffset(): void {
+  highestUpdateId = 0;
+}
+
+/**
+ * Tell Telegram every update seen so far is handled, so none of them is
+ * redelivered to the next process. Best-effort: this runs on the
+ * shutdown path, where a failure must never block exit.
+ */
+export async function confirmUpdates(bot: Bot): Promise<void> {
+  if (highestUpdateId === 0) return;
+  try {
+    await bot.api.getUpdates({
+      offset: highestUpdateId + 1,
+      limit: 1,
+      timeout: 0,
+    });
+    log("shutdown", `Confirmed Telegram updates through ${highestUpdateId}`);
+  } catch (err) {
+    logWarn(
+      "shutdown",
+      `Could not confirm Telegram update offset: ${err instanceof Error ? err.message : err}`,
+    );
+  }
+}