talon-agent 3.21.0 → 3.22.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "3.21.0",
+  "version": "3.22.1",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",
@@ -113,7 +113,7 @@
     "cross-spawn": "^7.0.6",
     "discord.js": "^14.16.3",
     "file-type": "^22.0.1",
-    "grammy": "^1.42.0",
+    "grammy": "^1.45.1",
     "liquidjs": "^10.27.0",
     "marked": "^18.0.0",
     "mem0ai": "^3.0.13",

package/src/app.ts

@@ -9,7 +9,7 @@
 import { getFrontends } from "./util/config.js";
 import { startUploadCleanup, stopUploadCleanup } from "./util/workspace.js";
 import { flushDatabase } from "./storage/db.js";
-import { getActiveCount } from "./core/engine/dispatcher.js";
+import { getActiveCount, stopAllTurns } from "./core/engine/dispatcher.js";
 import { startPulseTimer, stopPulseTimer } from "./core/background/pulse.js";
 import { stopPlanAlerts } from "./core/background/plan-alerts.js";
 import {
@@ -121,6 +121,7 @@ async function gracefulShutdown(signal: string): Promise<void> {
   shuttingDown = true;
   log("shutdown", `${signal} received, shutting down gracefully...`);
 
+  const deadlineAt = Date.now() + SHUTDOWN_TIMEOUT_MS;
   const forceTimer = setTimeout(() => {
     logError("shutdown", "Timeout exceeded, forcing exit");
     // Hand off even on the forced path. A restart must survive a
@@ -135,12 +136,17 @@ async function gracefulShutdown(signal: string): Promise<void> {
   }, SHUTDOWN_TIMEOUT_MS);
   forceTimer.unref();
 
-  // Drain in-flight queries: poll instead of a fixed sleep, so an idle
-  // daemon exits immediately and a busy one gets the full budget.
+  // Drain in-flight queries. A turn can legitimately run for minutes, so a
+  // drain that only waits can never succeed against one — ask every running
+  // turn to abort first, then poll for the aborts to settle so backends can
+  // flush partial state before the process exits.
   if (getActiveCount() > 0) {
+    const aborted = stopAllTurns();
     log(
       "shutdown",
-      `Waiting for ${getActiveCount()} in-flight queries to drain...`,
+      `Waiting for ${getActiveCount()} in-flight queries to drain` +
+        (aborted > 0 ? ` (abort requested for ${aborted})` : "") +
+        `...`,
     );
     const deadline = Date.now() + DRAIN_TIMEOUT_MS;
     while (getActiveCount() > 0 && Date.now() < deadline) {
@@ -177,7 +183,11 @@ async function gracefulShutdown(signal: string): Promise<void> {
   await shutdownStep("pulse timer", stopPulseTimer);
   await shutdownStep("heartbeat", async () => {
     stopHeartbeatTimer();
-    await awaitHeartbeat();
+    // Cap the wait by what's left of the force-timer budget (minus margin
+    // for the steps below). The default 10s wait plus a full 5s drain used
+    // to consume the entire 15s budget, so a slow heartbeat tripped the
+    // forced exit even though teardown was proceeding normally.
+    await awaitHeartbeat(Math.max(0, deadlineAt - Date.now() - 3_000));
   });
   await shutdownStep("cron timer", stopCronTimer);
   await shutdownStep("plan alerts", stopPlanAlerts);

package/src/backend/claude-sdk/handler.ts

@@ -67,8 +67,9 @@ import {
   recordFailedTurnAccounting,
   recordFlowViolation,
   formatTurnCache,
-  exceedsLookbackWindow,
-  estimateTurnBlocks,
+  crossTurnVerdict,
+  priorLookbackOverflow,
+  noteLookbackRisk,
   CACHE_LOOKBACK_BLOCKS,
 } from "../shared/index.js";
 
@@ -594,16 +595,24 @@ export async function* runChatTurn(
 
   // The aggregate `cache=NN%` can't distinguish a turn that reused the
   // previous turn's prefix from one that re-wrote it — see
-  // shared/cache-telemetry.ts. Append the cross-turn verdict when the
-  // provider gave us per-request usage to derive it from.
-  if (state.cacheStats && exceedsLookbackWindow(state.toolCalls)) {
-    logWarn(
-      "agent",
-      `[${chatId}] turn emitted ~${estimateTurnBlocks(state.toolCalls)} content ` +
-        `blocks (> ${CACHE_LOOKBACK_BLOCKS} lookback) — the next turn's cache ` +
-        `breakpoint may not find this turn's prefix`,
-    );
+  // shared/cache-telemetry.ts. A lookback overflow only *predicts* a miss,
+  // so warn when this turn's verdict proves the previous turn's overflow
+  // cost a prefix re-write, then record this turn's overflow for the next.
+  if (state.cacheStats) {
+    const overflow = priorLookbackOverflow(chatId);
+    if (
+      overflow !== undefined &&
+      crossTurnVerdict(state.cacheStats) === "miss"
+    ) {
+      logWarn(
+        "agent",
+        `[${chatId}] previous turn emitted ~${overflow} content blocks ` +
+          `(> ${CACHE_LOOKBACK_BLOCKS} lookback) and this turn's prefix ` +
+          `missed — that turn's cache write was likely never read`,
+      );
+    }
   }
+  noteLookbackRisk(chatId, state.toolCalls);
 
   log(
     "agent",

package/src/backend/remote-server/mcp.ts

@@ -29,7 +29,7 @@
  * registrations run concurrently through the hub; later turns skip them.
  */
 
-import { log, logWarn } from "../../util/log.js";
+import { log, logDebug, logWarn } from "../../util/log.js";
 import {
   talonHubUrl,
   pluginHubUrl,
@@ -62,6 +62,9 @@ export const TALON_PLUGIN_MCP_SERVER_NAME = "talon-plugin";
  */
 const SLOW_MCP_REGISTRATION_MS = 1000;
 
+/** Servers whose registration failure was already warned about (see below). */
+const warnedMcpRegistrationFailures = new Set<string>();
+
 /**
  * OpenCode's `/experimental/tool/ids` endpoint omits dynamically registered
  * MCP tools despite its API description. Synthesize Talon's known MCP ids so
@@ -253,6 +256,7 @@ export async function ensurePluginMcpServers<TClient extends RemoteAgentClient>(
         state.registeredMcpServers.add(serverName);
         state.registeredMcpTools.set(serverName, toolNames);
         byPlugin.set(name, serverName);
+        warnedMcpRegistrationFailures.delete(serverName);
         const ms = Date.now() - startedAt;
         log(
           "agent",
@@ -261,7 +265,16 @@ export async function ensurePluginMcpServers<TClient extends RemoteAgentClient>(
         );
         return serverName;
       } catch (err) {
-        logWarn(
+        // Warn once per server, then debug: registration re-runs at the
+        // head of every turn, so a dead backing service (an offline
+        // browser endpoint, say) would otherwise emit one warning per
+        // turn for the whole outage. Success clears the latch so the
+        // next outage warns again.
+        const level = warnedMcpRegistrationFailures.has(serverName)
+          ? logDebug
+          : logWarn;
+        warnedMcpRegistrationFailures.add(serverName);
+        level(
           "agent",
           `Plugin MCP registration failed for ${serverName}: ${errMsg(err)}`,
         );

package/src/backend/shared/cache-telemetry.ts

@@ -154,6 +154,48 @@ export function exceedsLookbackWindow(toolCalls: number): boolean {
   return estimateTurnBlocks(toolCalls) > CACHE_LOOKBACK_BLOCKS;
 }
 
+/**
+ * Per-chat estimated block count of the last turn that overflowed the
+ * lookback window. Overflow is only a *prediction* of a cache miss — the
+ * proof is the NEXT turn's cross-turn verdict, so the overflow is recorded
+ * here and the warning waits for that verdict instead of firing on every
+ * tool-heavy turn. Bounded like `lastToolSets` below.
+ */
+const lookbackOverflows = new Map<string, number>();
+
+/**
+ * Record whether this turn plausibly overflowed the lookback window, so the
+ * next turn can attribute a cross-turn miss to it.
+ */
+export function noteLookbackRisk(chatId: string, toolCalls: number): void {
+  if (!exceedsLookbackWindow(toolCalls)) {
+    lookbackOverflows.delete(chatId);
+    return;
+  }
+  if (
+    lookbackOverflows.size >= MAX_TRACKED_CHATS &&
+    !lookbackOverflows.has(chatId)
+  ) {
+    const oldest = lookbackOverflows.keys().next().value;
+    if (oldest !== undefined) lookbackOverflows.delete(oldest);
+  }
+  lookbackOverflows.set(chatId, estimateTurnBlocks(toolCalls));
+}
+
+/**
+ * Estimated block count of the chat's previous turn IF it overflowed the
+ * lookback window, else undefined. Read this before `noteLookbackRisk`
+ * records the current turn.
+ */
+export function priorLookbackOverflow(chatId: string): number | undefined {
+  return lookbackOverflows.get(chatId);
+}
+
+/** Drop all recorded overflows (tests / explicit reset). */
+export function resetLookbackRisk(): void {
+  lookbackOverflows.clear();
+}
+
 // ── Cacheable minimum ──────────────────────────────────────────────────────
 
 /**

package/src/backend/shared/index.ts

@@ -73,8 +73,9 @@ export {
 // barrel discipline the prompt/ barrel was just trimmed to.
 export {
   formatTurnCache,
-  estimateTurnBlocks,
-  exceedsLookbackWindow,
+  crossTurnVerdict,
+  priorLookbackOverflow,
+  noteLookbackRisk,
   CACHE_LOOKBACK_BLOCKS,
 } from "./cache-telemetry.js";
 

package/src/core/engine/dispatcher.ts

@@ -66,6 +66,16 @@ export function stopCurrentTurn(chatId: string): KillOutcome {
   return taskTable.killRunningTurn(chatId);
 }
 
+/**
+ * Request an abort of every chat's running turn. The shutdown drain calls
+ * this before polling `getActiveCount` — a turn can legitimately run for
+ * minutes, so a drain that only waits can never succeed against one.
+ * Returns the number of kill requests issued.
+ */
+export function stopAllTurns(): number {
+  return taskTable.killAllRunningTurns();
+}
+
 /**
  * Execute an AI query with full lifecycle management.
  * Same-chat queries are serialized (FIFO) to avoid session conflicts.

package/src/core/errors.ts

@@ -33,6 +33,17 @@ type ErrorReason =
 const USAGE_LIMIT_RE =
   /you['’]ve hit your .{0,40}limit|you['’]re out of extra usage|claude ai usage limit reached|usage limit reached/i;
 
+/**
+ * Ceiling on how long a failed attempt may have run and still earn the
+ * frontend queues' blind retry. `retryable` means "a short pause may clear
+ * it", which holds for a 429 or a dropped socket but not for an attempt
+ * that already burned minutes before failing (e.g. the 600s remote turn
+ * deadline — its rejection is `name: "TimeoutError"`, classified as
+ * transient network). Turns serialize per chat, so retrying such an
+ * attempt doubles the stall for every message queued behind it.
+ */
+export const RETRY_ELAPSED_CAP_MS = 120_000;
+
 // ── TalonError class ────────────────────────────────────────────────────────
 
 export class TalonError extends Error {

package/src/core/mcp-hub/children.ts

@@ -62,6 +62,31 @@ type ChildEntry = {
 const children = new Map<string, ChildEntry>();
 const inflight = new Map<string, Promise<ChildHandle>>();
 
+/**
+ * Negative cache for spawn failures. A child whose backing service is down
+ * (e.g. playwright-tools with its browser endpoint offline) dies at the
+ * connect handshake, and without this every single turn re-paid the
+ * spawn+handshake (~600ms) and re-logged the failure for the whole outage.
+ * Failures back off exponentially; the first attempt after the window
+ * clears the entry on success, so recovery costs one turn.
+ */
+type SpawnFailure = { at: number; count: number; error: unknown };
+const spawnFailures = new Map<string, SpawnFailure>();
+const FAILURE_BACKOFF_BASE_MS = 30_000;
+const FAILURE_BACKOFF_MAX_MS = 10 * 60_000;
+
+function failureBackoffMs(count: number): number {
+  return Math.min(
+    FAILURE_BACKOFF_BASE_MS * 2 ** (count - 1),
+    FAILURE_BACKOFF_MAX_MS,
+  );
+}
+
+/** Test seam: forget recorded spawn failures. */
+export function resetSpawnFailures(): void {
+  spawnFailures.clear();
+}
+
 /** Idle TTL for hub children; tunable for tests / tight deployments. */
 function idleTtlMs(): number {
   const raw = Number(process.env.TALON_MCP_HUB_IDLE_MS);
@@ -168,9 +193,28 @@ export function acquireChild(
   const pending = inflight.get(key);
   if (pending) return pending;
 
+  const failure = spawnFailures.get(key);
+  if (failure && Date.now() - failure.at < failureBackoffMs(failure.count)) {
+    return Promise.reject(
+      failure.error instanceof Error
+        ? failure.error
+        : new Error(String(failure.error)),
+    );
+  }
+
   const promise = (async () => {
     try {
-      return await spawnChild(key, spec());
+      const handle = await spawnChild(key, spec());
+      spawnFailures.delete(key);
+      return handle;
+    } catch (err) {
+      const prior = spawnFailures.get(key);
+      spawnFailures.set(key, {
+        at: Date.now(),
+        count: (prior?.count ?? 0) + 1,
+        error: err,
+      });
+      throw err;
     } finally {
       inflight.delete(key);
     }

package/src/core/tasks/table.ts

@@ -122,6 +122,20 @@ export class TaskTable {
     return { ok: true };
   }
 
+  /**
+   * Request an abort of every running turn, regardless of chat — the
+   * shutdown drain's lever. Returns the number of kill requests issued.
+   */
+  killAllRunningTurns(): number {
+    let killed = 0;
+    for (const [id, task] of this.live) {
+      if (task.record.kind === "turn" && task.record.state === "running") {
+        if (this.kill(id).ok) killed++;
+      }
+    }
+    return killed;
+  }
+
   /**
    * Request an abort for the turn currently running in one chat. Queued turns
    * are deliberately ignored: `/stop` means "stop what is happening now",

package/src/core/tools/index.ts

@@ -22,6 +22,7 @@ import { webTools } from "./web.js";
 import { adminTools } from "./admin.js";
 import { modelTools } from "./models.js";
 import { meshTools } from "./mesh.js";
+import { moderationTools } from "./moderation.js";
 import { nativeTools } from "./native.js";
 
 /** All built-in tool definitions. */
@@ -41,6 +42,7 @@ export const ALL_TOOLS: readonly ToolDefinition[] = [
   ...adminTools,
   ...modelTools,
   ...meshTools,
+  ...moderationTools,
 ];
 
 /**

package/src/core/tools/messaging.ts

@@ -135,7 +135,10 @@ Examples:
   Dice: send(type="dice")
   Location: send(type="location", latitude=37.7749, longitude=-122.4194)
   Sticker by feeling: send(type="sticker", emoji="😂") — picks a matching sticker from your saved packs (add set_name to pin one pack)
-  Sticker by id: send(type="sticker", file_id="CAACAgI...")`,
+  Sticker by id: send(type="sticker", file_id="CAACAgI...")
+  Album: send(type="album", media=[{"type":"photo","file_path":"a.jpg"},{"type":"photo","url":"https://…/b.jpg","caption":"the good one"}]) — 2-10 photos/videos as one grouped message
+  Round video: send(type="video_note", file_path="/path/clip.mp4") — circular video bubble (square video, ≤60s)
+  Venue: send(type="venue", latitude=53.34, longitude=-6.26, title="The Long Hall", address="51 South Great George's St")`,
     schema: {
       type: z
         .enum([
@@ -151,6 +154,9 @@ Examples:
           "location",
           "contact",
           "dice",
+          "album",
+          "video_note",
+          "venue",
         ])
         .describe("Content type to send"),
       text: z
@@ -208,7 +214,30 @@ Examples:
       phone_number: z.string().optional().describe("Contact phone"),
       first_name: z.string().optional().describe("Contact first name"),
       last_name: z.string().optional().describe("Contact last name"),
-      title: z.string().optional().describe("Audio title (for type=audio)"),
+      title: z
+        .string()
+        .optional()
+        .describe("Audio title (type=audio) or venue name (type=venue)"),
+      address: z
+        .string()
+        .optional()
+        .describe("Venue street address (for type=venue)"),
+      media: z
+        .array(
+          z.object({
+            type: z
+              .enum(["photo", "video", "document", "audio"])
+              .describe("Kind of this album item"),
+            file_path: z.string().optional(),
+            url: z.string().optional(),
+            file_id: z.string().optional(),
+            caption: z.string().optional(),
+          }),
+        )
+        .optional()
+        .describe(
+          "Album items (for type=album): 2-10 entries, each sourced from file_path, url, or file_id. Photos and videos mix; documents/audio group only with their own kind.",
+        ),
       performer: z
         .string()
         .optional()
@@ -230,9 +259,41 @@ Examples:
         .describe(
           "Target chat ID. Omit to send to the current chat (chat mode). Required from heartbeat mode where there is no ambient chat — use list_chats or known IDs from memory. Telegram supergroup/channel IDs are negative (e.g. -1001426819337); user DMs are positive.",
         ),
+      silent: z
+        .boolean()
+        .optional()
+        .describe("Send without a notification sound (Telegram)"),
+      protect: z
+        .boolean()
+        .optional()
+        .describe("Protect content from forwarding and saving (Telegram)"),
+      spoiler: z
+        .boolean()
+        .optional()
+        .describe(
+          "Blur photo/video/animation behind a spoiler tap-to-reveal (Telegram)",
+        ),
+      no_link_preview: z
+        .boolean()
+        .optional()
+        .describe("Disable the link preview for type=text (Telegram)"),
+      thread_id: z
+        .union([z.number(), z.literal("general")])
+        .optional()
+        .describe(
+          'Forum topic to post into (Telegram supergroups with topics). Defaults to the topic the conversation is happening in; pass "general" to force the General topic.',
+        ),
     },
     execute: async (params, bridge) => {
       const { type } = params;
+      // Delivery modifiers every Telegram send action understands. Harmless
+      // on frontends that don't (handlers read only the fields they know).
+      const mods = {
+        silent: params.silent,
+        protect: params.protect,
+        spoiler: params.spoiler,
+        thread_id: params.thread_id,
+      };
       // Thread chat_id through to every bridge call so heartbeat / dream
       // outbound (no ambient chat) gets routed by the explicit chat_id.
       // `createBridge` at src/core/tools/bridge.ts:29 reads
@@ -253,6 +314,7 @@ Examples:
               delay_seconds: params.delay_seconds,
               rows: params.buttons,
               reply_to_message_id: params.reply_to,
+              ...mods,
               chat_id,
             });
           }
@@ -261,12 +323,15 @@ Examples:
               text: params.text,
               rows: params.buttons,
               reply_to_message_id: params.reply_to,
+              ...mods,
               chat_id,
             });
           }
           return bridge("send_message", {
             text: params.text,
             reply_to_message_id: params.reply_to,
+            no_link_preview: params.no_link_preview,
+            ...mods,
             chat_id,
           });
         }
@@ -277,6 +342,7 @@ Examples:
             file_id: params.file_id,
             caption: params.caption,
             reply_to: params.reply_to,
+            ...mods,
             chat_id,
           });
         case "file":
@@ -286,6 +352,7 @@ Examples:
             file_id: params.file_id,
             caption: params.caption,
             reply_to: params.reply_to,
+            ...mods,
             chat_id,
           });
         case "video":
@@ -295,6 +362,7 @@ Examples:
             file_id: params.file_id,
             caption: params.caption,
             reply_to: params.reply_to,
+            ...mods,
             chat_id,
           });
         case "voice":
@@ -304,6 +372,7 @@ Examples:
             file_id: params.file_id,
             caption: params.caption,
             reply_to: params.reply_to,
+            ...mods,
             chat_id,
           });
         case "audio":
@@ -315,6 +384,7 @@ Examples:
             title: params.title,
             performer: params.performer,
             reply_to: params.reply_to,
+            ...mods,
             chat_id,
           });
         case "animation":
@@ -324,6 +394,7 @@ Examples:
             file_id: params.file_id,
             caption: params.caption,
             reply_to: params.reply_to,
+            ...mods,
             chat_id,
           });
         case "sticker":
@@ -333,6 +404,7 @@ Examples:
             emoji: params.emoji,
             set_name: params.set_name,
             reply_to: params.reply_to,
+            ...mods,
             chat_id,
           });
         case "poll":
@@ -344,6 +416,7 @@ Examples:
             explanation: params.explanation,
             type: params.correct_option_id !== undefined ? "quiz" : "regular",
             reply_to: params.reply_to,
+            ...mods,
             chat_id,
           });
         case "location":
@@ -351,6 +424,7 @@ Examples:
             latitude: params.latitude,
             longitude: params.longitude,
             reply_to: params.reply_to,
+            ...mods,
             chat_id,
           });
         case "contact":
@@ -359,12 +433,40 @@ Examples:
             first_name: params.first_name,
             last_name: params.last_name,
             reply_to: params.reply_to,
+            ...mods,
             chat_id,
           });
         case "dice":
           return bridge("send_dice", {
             emoji: params.emoji,
             reply_to: params.reply_to,
+            ...mods,
+            chat_id,
+          });
+        case "album":
+          return bridge("send_media_group", {
+            media: params.media,
+            reply_to: params.reply_to,
+            ...mods,
+            chat_id,
+          });
+        case "video_note":
+          return bridge("send_video_note", {
+            file_path: params.file_path,
+            url: params.url,
+            file_id: params.file_id,
+            reply_to: params.reply_to,
+            ...mods,
+            chat_id,
+          });
+        case "venue":
+          return bridge("send_venue", {
+            latitude: params.latitude,
+            longitude: params.longitude,
+            title: params.title,
+            address: params.address,
+            reply_to: params.reply_to,
+            ...mods,
             chat_id,
           });
         default:
@@ -479,8 +581,16 @@ Valid emoji: 👍 👎 ❤ 🔥 🥰 👏 😁 🤔 🤯 😱 🤬 😢 🎉
   // ── edit_message ──────────────────────────────────────────────────────
   {
     name: "edit_message",
-    description: "Edit a previously sent message.",
-    schema: { message_id: snowflakeOrIdSchema, text: z.string() },
+    description:
+      "Edit a previously sent message. For a media message (photo/video/file), pass is_caption=true to edit its caption instead of message text.",
+    schema: {
+      message_id: snowflakeOrIdSchema,
+      text: z.string(),
+      is_caption: z
+        .boolean()
+        .optional()
+        .describe("Edit the media caption rather than message text (Telegram)"),
+    },
     execute: (params, bridge) => bridge("edit_message", params),
     frontends: ["telegram", "discord", "native"],
     tag: "messaging",
@@ -489,8 +599,15 @@ Valid emoji: 👍 👎 ❤ 🔥 🥰 👏 😁 🤔 🤯 😱 🤬 😢 🎉
   // ── delete_message ────────────────────────────────────────────────────
   {
     name: "delete_message",
-    description: "Delete a message.",
-    schema: { message_id: snowflakeOrIdSchema },
+    description:
+      "Delete a message — or several at once via message_ids (Telegram; ids the bot can't delete are skipped).",
+    schema: {
+      message_id: snowflakeOrIdSchema.optional(),
+      message_ids: z
+        .array(snowflakeOrIdSchema)
+        .optional()
+        .describe("Bulk delete these message IDs (Telegram)"),
+    },
     execute: (params, bridge) => bridge("delete_message", params),
     frontends: ["telegram", "discord", "native"],
     tag: "messaging",
@@ -499,13 +616,42 @@ Valid emoji: 👍 👎 ❤ 🔥 🥰 👏 😁 🤔 🤯 😱 🤬 😢 🎉
   // ── forward_message ───────────────────────────────────────────────────
   {
     name: "forward_message",
-    description: "Forward a message within the chat.",
-    schema: { message_id: snowflakeOrIdSchema },
+    description:
+      "Forward a message. Defaults to within the current chat; from_chat_id / to_chat_id forward across chats the bot is in, and message_ids forwards a batch (albums stay grouped) (Telegram).",
+    schema: {
+      message_id: snowflakeOrIdSchema.optional(),
+      message_ids: z
+        .array(snowflakeOrIdSchema)
+        .optional()
+        .describe("Forward these messages as a batch (Telegram)"),
+      from_chat_id: chatIdSchema
+        .optional()
+        .describe("Source chat (default: current chat)"),
+      to_chat_id: chatIdSchema
+        .optional()
+        .describe("Destination chat (default: current chat)"),
+    },
     execute: (params, bridge) => bridge("forward_message", params),
     frontends: ["telegram", "discord"],
     tag: "messaging",
   },
 
+  // ── copy_message ──────────────────────────────────────────────────────
+  {
+    name: "copy_message",
+    description:
+      "Repost a message without the 'forwarded from' header. Same cross-chat and batch semantics as forward_message (Telegram).",
+    schema: {
+      message_id: snowflakeOrIdSchema.optional(),
+      message_ids: z.array(snowflakeOrIdSchema).optional(),
+      from_chat_id: chatIdSchema.optional(),
+      to_chat_id: chatIdSchema.optional(),
+    },
+    execute: (params, bridge) => bridge("copy_message", params),
+    frontends: ["telegram"],
+    tag: "messaging",
+  },
+
   // ── pin_message ───────────────────────────────────────────────────────
   {
     name: "pin_message",