@llblab/pi-kit 0.5.2 → 0.7.0

package/node_modules/@llblab/pi-telegram/lib/lifecycle.ts

@@ -37,9 +37,15 @@ export function setResetTransportReplyDedup(fn: () => void): void {
 
 export function createAgentStartDedupHook(
   inner: (event: AgentStartEvent, ctx: ExtensionContext) => Promise<void>,
+  schedulePublication?: (task: () => Promise<void>) => void,
 ): (event: AgentStartEvent, ctx: ExtensionContext) => Promise<void> {
   return async (event, ctx) => {
-    if (resetTransportReplyDedupFn) resetTransportReplyDedupFn();
+    const reset = resetTransportReplyDedupFn;
+    if (reset) {
+      // A new turn must not erase the anchor of a final still ahead in the FIFO.
+      if (schedulePublication) schedulePublication(async () => { reset(); });
+      else reset();
+    }
     return inner(event, ctx);
   };
 }

package/node_modules/@llblab/pi-telegram/lib/locks.ts

@@ -1108,6 +1108,7 @@ export function createTelegramDirectDeliveryOwnershipChecker<
 export interface TelegramLockedPollingStartOptions {
   force?: boolean;
   forceFreshLeaderThread?: boolean;
+  requestedThreadName?: string;
   election?: { expectedOwner?: TelegramLockEntry };
   onAcquired?: () => Promise<void> | void;
 }
@@ -1131,6 +1132,10 @@ export interface TelegramLockedPollingRuntime<
     ctx: TContext,
     owner: TelegramLockEntry,
   ) => boolean | undefined | Promise<boolean | undefined>;
+  restoreFollowerWithOwner?: (
+    ctx: TContext,
+    owner: TelegramLockEntry,
+  ) => boolean | undefined | Promise<boolean | undefined>;
   stopFollowerRegistration?: () => void;
 }
 
@@ -1151,6 +1156,10 @@ export interface TelegramLockedPollingRuntimeDeps<
     ctx: TContext,
     owner: TelegramLockEntry,
   ) => boolean | undefined | Promise<boolean | undefined>;
+  restoreFollowerWithOwner?: (
+    ctx: TContext,
+    owner: TelegramLockEntry,
+  ) => boolean | undefined | Promise<boolean | undefined>;
   stopFollowerRegistration?: () => void;
   onTransportAvailabilityChanged?: () => void;
   transportMonitor?: { start: (ctx: TContext) => void; stop: () => void };
@@ -1198,6 +1207,7 @@ export function createTelegramLockedPollingRuntime<
     stopOwnershipWatcher();
     if (sessionAutoStartRun) {
       await sessionAutoStartRun;
+      deps.stopFollowerRegistration?.();
     }
     if (ownershipStop) {
       await ownershipStop;
@@ -1452,10 +1462,14 @@ export function createTelegramLockedPollingRuntime<
       const canHandoffSameProcess =
         state?.kind === "active-here" &&
         (!state.lock.cwd || state.lock.cwd === ctx.cwd);
+      const canRestoreRememberedFollower =
+        state?.kind === "active-elsewhere" &&
+        deps.restoreFollowerWithOwner !== undefined;
       if (
         !ownsCurrentLock &&
         !canResumeStaleSameCwd &&
-        !canHandoffSameProcess
+        !canHandoffSameProcess &&
+        !canRestoreRememberedFollower
       ) {
         return;
       }
@@ -1466,11 +1480,27 @@ export function createTelegramLockedPollingRuntime<
       const startedAtMs = Date.now();
       deps.recordRuntimeEvent?.("lock", "Telegram auto-start scheduled", {
         phase: "auto-start-scheduled",
+        mode: canRestoreRememberedFollower ? "follower-restore" : "leader",
       });
       const run = (async () => {
         await new Promise((resolve) => setTimeout(resolve, 0));
         if (ownershipStop) await ownershipStop;
         if (!isCurrent()) return;
+        if (canRestoreRememberedFollower && state?.kind === "active-elsewhere") {
+          const restored = await deps.restoreFollowerWithOwner?.(
+            ctx,
+            state.lock,
+          );
+          if (!isCurrent() || !restored) return;
+          deps.onTransportAvailabilityChanged?.();
+          deps.updateStatus(ctx);
+          deps.recordRuntimeEvent?.(
+            "bus",
+            "Telegram follower auto-connect completed",
+            { phase: "follower-auto-connect" },
+          );
+          return;
+        }
         if (canResumeStaleSameCwd || canHandoffSameProcess) {
           const acquired = deps.lock.acquire(
             ctx,
@@ -1505,6 +1535,13 @@ export function createTelegramLockedPollingRuntime<
           return registered === true;
         }
       : undefined,
+    restoreFollowerWithOwner: deps.restoreFollowerWithOwner
+      ? async (ctx, owner) => {
+          const restored = await deps.restoreFollowerWithOwner?.(ctx, owner);
+          if (restored) deps.updateStatus(ctx);
+          return restored === true;
+        }
+      : undefined,
     stopFollowerRegistration: deps.stopFollowerRegistration,
   };
 }

package/node_modules/@llblab/pi-telegram/lib/menu-settings.ts

@@ -8,6 +8,7 @@ import type {
   TelegramActivityVerbosity,
   TelegramAssistantRenderingMode,
   TelegramTimeMode,
+  TelegramThreadDisplayMode,
 } from "./config.ts";
 import type { TelegramInlineKeyboardMarkup } from "./keyboard.ts";
 import type { TelegramModelMenuState } from "./menu-model.ts";
@@ -21,6 +22,7 @@ import type { TelegramVoiceReplyMode } from "./voice.ts";
 export type TelegramSettingsMenuReplyMarkup = TelegramInlineKeyboardMarkup;
 
 export interface TelegramSettingsStateDeps {
+  getThreadDisplayMode?: () => TelegramThreadDisplayMode | undefined;
   areDraftPreviewsEnabled: () => boolean;
   getAssistantRenderingMode: () => TelegramAssistantRenderingMode;
   getActivityVerbosity: () => TelegramActivityVerbosity;
@@ -31,6 +33,7 @@ export interface TelegramSettingsStateDeps {
 }
 
 export interface TelegramSettingsMutationDeps extends TelegramSettingsStateDeps {
+  setThreadDisplayMode?: (mode: TelegramThreadDisplayMode) => Promise<void>;
   setDraftPreviewsEnabled: (enabled: boolean) => Promise<void>;
   setAssistantRenderingMode: (
     mode: TelegramAssistantRenderingMode,
@@ -43,6 +46,11 @@ export interface TelegramSettingsMutationDeps extends TelegramSettingsStateDeps
   ) => Promise<void>;
   setTimeInjectionMode: (mode: TelegramTimeMode) => Promise<void>;
   setAutomaticThreadCleanupEnabled: (enabled: boolean) => Promise<void>;
+  reviewInactiveThreads?: () => Promise<{ count: number; operationId?: string }>;
+  cleanInactiveThreads?: (operationId: string) => Promise<{
+    deleted: number; outcomeUnknown: number; blocked?: number;
+    recovery?: "commit-ready" | "deletion-outcome-unknown" | "authority-blocked";
+  }>;
 }
 
 export interface TelegramSettingsMenuOpenDeps<
@@ -137,6 +145,7 @@ export interface TelegramSettingsMenuRuntimeDeps<
 export const SETTINGS_MENU_TITLE = "<b>⚙️ Settings:</b>";
 export const AUTOMATIC_THREAD_CLEANUP_SETTINGS_TITLE =
   "<b>🧹 Thread cleanup:</b>";
+export const INACTIVE_THREAD_REVIEW_TITLE = "<b>🔎 Inactive tabs review:</b>";
 export const DRAFT_PREVIEWS_SETTINGS_TITLE = "<b>📝 Draft previews:</b>";
 export const ASSISTANT_RENDERING_SETTINGS_TITLE =
   "<b>🧾 Assistant rendering:</b>";
@@ -145,6 +154,7 @@ export const ACTIVITY_VERBOSITY_SETTINGS_TITLE =
 export const TIME_INJECTION_MODE_SETTINGS_TITLE =
   "<b>🕒 Time injection mode:</b>";
 export const VOICE_REPLY_MODE_SETTINGS_TITLE = "<b>👄 Voice reply mode:</b>";
+export const THREAD_DISPLAY_SETTINGS_TITLE = "<b>🧵 Thread display:</b>";
 
 function getVoiceReplyModeLabel(mode: TelegramVoiceReplyMode): string {
   return mode;
@@ -165,6 +175,18 @@ export function buildTelegramSettingsMenuText(): string {
   return SETTINGS_MENU_TITLE;
 }
 
+export function buildThreadDisplaySettingsText(mode: TelegramThreadDisplayMode): string {
+  return [
+    `${THREAD_DISPLAY_SETTINGS_TITLE} <code>${mode}</code>`,
+    "",
+    "Choose how this bot profile labels Telegram tabs and Pi terminal status. Each slot is unique across this bot profile.",
+    "",
+    "<code>-</code> <code>letters</code> (default): show the unique slot, such as <b><i>A</i></b> or <b><i>B</i></b>.",
+    "<code>-</code> <code>directories</code>: show the directory, such as <b><i>extensions</i></b>; shared Workspaces keep slot suffixes, such as <b><i>extensions_a</i></b> and <b><i>extensions_c</i></b>.",
+    "A manual <code>/name Name</code> overrides this Thread display name until reset.",
+  ].join("\n");
+}
+
 export function buildAutomaticThreadCleanupSettingsText(
   enabled: boolean,
 ): string {
@@ -175,17 +197,43 @@ export function buildAutomaticThreadCleanupSettingsText(
     "",
     "<code>-</code> <code>on</code> (default): delete the bound thread and release Telegram authority on graceful quit.",
     "<code>-</code> <code>off</code>: preserve the tab as a restart hint; manual <code>/telegram-disconnect</code> still confirms and deletes it.",
+    "",
+    "Review inactive tabs checks current owner and work evidence. Review never deletes tabs.",
   ].join("\n");
 }
 
+export function buildInactiveThreadReviewText(count: number): string {
+  return [INACTIVE_THREAD_REVIEW_TITLE, "",
+    `${count} proven inactive tab${count === 1 ? "" : "s"}.`,
+    "No tabs were deleted.",
+    "Deletion requires a separate confirmed Clean action.",
+  ].join("\n");
+}
+
+export function buildInactiveThreadReviewReplyMarkup(
+  operationId?: string,
+  canCleanInactiveThreads = false,
+): TelegramSettingsMenuReplyMarkup {
+  const validOperationId = typeof operationId === "string" &&
+    /^thread-cleanup:[a-f0-9]{32}$/u.test(operationId);
+  return { inline_keyboard: [
+    [{ text: "⬆️ Back to Thread cleanup",
+      callback_data: "settings:open:automatic-thread-cleanup" }],
+    ...(canCleanInactiveThreads && validOperationId ? [[{
+      text: "🧹 Clean inactive tabs",
+      callback_data: `settings:clean:${operationId}`,
+    }]] : []),
+  ] };
+}
+
 export function buildDraftPreviewsSettingsText(enabled: boolean): string {
   return [
     `${DRAFT_PREVIEWS_SETTINGS_TITLE} <code>${enabled ? "on" : "off"}</code>`,
     "",
     "Show live answer drafts while the model is answering.",
     "",
-    "<code>-</code> <code>on</code>: stream safe Telegram Rich Draft frames before the final answer.",
-    "<code>-</code> <code>off</code> (default): show native active status, then send one final answer.",
+    "<code>-</code> <code>on</code> (default): stream safe Telegram Rich Draft frames before the final answer.",
+    "<code>-</code> <code>off</code>: show native active status, then send one final answer.",
   ].join("\n");
 }
 
@@ -259,6 +307,7 @@ export function buildTelegramSettingsMenuReplyMarkup(
   voiceReplyModeConfigured = true,
   automaticThreadCleanupEnabled = true,
   activityVerbosity: TelegramActivityVerbosity = "quiet",
+  threadDisplayMode?: TelegramThreadDisplayMode,
 ): TelegramSettingsMenuReplyMarkup {
   const hasRenderingMode =
     assistantRenderingModeOrVoiceReplyMode === "rich" ||
@@ -317,6 +366,10 @@ export function buildTelegramSettingsMenuReplyMarkup(
       callback_data: "settings:open:automatic-thread-cleanup",
     },
   ];
+  if (threadDisplayMode) settingsButtons.push({
+    text: `🧵 Thread display: ${threadDisplayMode}`,
+    callback_data: "settings:open:thread-display",
+  });
   if (sectionRegistry) {
     const extensionRows = getTelegramExtensionSettingsRows(sectionRegistry);
     settingsButtons.push(
@@ -349,6 +402,7 @@ export async function openTelegramSettingsMenu<
       deps.isVoiceReplyModeConfigured(),
       deps.isAutomaticThreadCleanupEnabled(),
       deps.getActivityVerbosity(),
+      deps.getThreadDisplayMode?.(),
     ),
   );
   if (messageId === undefined) return;
@@ -357,8 +411,19 @@ export async function openTelegramSettingsMenu<
   deps.storeModelMenuState(state);
 }
 
+export function buildThreadDisplaySettingsReplyMarkup(mode: TelegramThreadDisplayMode): TelegramSettingsMenuReplyMarkup {
+  return { inline_keyboard: [
+    [{ text: "⬆️ Back", callback_data: "settings:list" }],
+    ...(["letters", "directories"] as const).map((value) => [{
+      text: `${mode === value ? "🟢 " : ""}${value}`,
+      callback_data: `settings:set:thread-display:${value}`,
+    }]),
+  ] };
+}
+
 export function buildAutomaticThreadCleanupSettingsReplyMarkup(
   enabled: boolean,
+  canReviewInactiveThreads = false,
 ): TelegramSettingsMenuReplyMarkup {
   return {
     inline_keyboard: [
@@ -373,6 +438,10 @@ export function buildAutomaticThreadCleanupSettingsReplyMarkup(
           callback_data: "settings:set:automatic-thread-cleanup:off",
         },
       ],
+      ...(canReviewInactiveThreads ? [[{
+        text: "🔎 Review inactive tabs",
+        callback_data: "settings:review:inactive-threads",
+      }]] : []),
     ],
   };
 }
@@ -417,21 +486,16 @@ export function buildAssistantRenderingSettingsReplyMarkup(
 export function buildActivityVerbositySettingsReplyMarkup(
   verbosity: TelegramActivityVerbosity,
 ): TelegramSettingsMenuReplyMarkup {
-  const values: TelegramActivityVerbosity[] = [
-    "quiet",
-    "thinking",
-    "tools",
-    "verbose",
-  ];
+  const button = (value: TelegramActivityVerbosity) => ({
+    text: `${value === verbosity ? "🟢 " : ""}${value}`,
+    callback_data: `settings:set:activity-verbosity:${value}`,
+  });
   return {
     inline_keyboard: [
       [{ text: "⬆️ Back", callback_data: "settings:list" }],
-      ...values.map((value) => [
-        {
-          text: `${value === verbosity ? "🟢 " : ""}${value}`,
-          callback_data: `settings:set:activity-verbosity:${value}`,
-        },
-      ]),
+      [button("quiet")],
+      [button("thinking"), button("tools")],
+      [button("verbose")],
     ],
   };
 }
@@ -487,6 +551,7 @@ export async function updateTelegramSettingsMenuMessage(
       deps.isVoiceReplyModeConfigured(),
       deps.isAutomaticThreadCleanupEnabled(),
       deps.getActivityVerbosity(),
+      deps.getThreadDisplayMode?.(),
     ),
   );
 }
@@ -497,7 +562,7 @@ export async function updateAutomaticThreadCleanupSettingsMessage(
   const enabled = deps.isAutomaticThreadCleanupEnabled();
   await deps.updateSettingsMessage(
     buildAutomaticThreadCleanupSettingsText(enabled),
-    buildAutomaticThreadCleanupSettingsReplyMarkup(enabled),
+    buildAutomaticThreadCleanupSettingsReplyMarkup(enabled, !!deps.reviewInactiveThreads),
   );
 }
 
@@ -558,6 +623,36 @@ export async function handleTelegramSettingsMenuCallbackAction(
   deps: TelegramSettingsMenuCallbackDeps,
 ): Promise<boolean> {
   if (!data?.startsWith("settings:")) return false;
+  if (data === "settings:open:thread-display" || data.startsWith("settings:set:thread-display:")) {
+    if (!deps.getThreadDisplayMode?.() || !deps.setThreadDisplayMode) {
+      await deps.answerCallbackQuery(callbackQueryId, "Thread display requires Threaded Mode and a connected instance.");
+      return true;
+    }
+    if (data.startsWith("settings:set:thread-display:")) {
+      const mode = data.slice("settings:set:thread-display:".length);
+      if (mode !== "letters" && mode !== "names" && mode !== "directories") {
+        await deps.answerCallbackQuery(callbackQueryId, "Unknown Thread display mode.");
+        return true;
+      }
+      try {
+        await deps.setThreadDisplayMode(mode);
+      } catch {
+        await deps.answerCallbackQuery(callbackQueryId, "Thread display was not fully applied. The preference may be saved; retry after checking the leader.");
+        return true;
+      }
+    }
+    const mode = deps.getThreadDisplayMode();
+    if (!mode) {
+      await deps.answerCallbackQuery(callbackQueryId, "Threaded Mode is no longer available.");
+      return true;
+    }
+    await deps.updateSettingsMessage(
+      buildThreadDisplaySettingsText(mode),
+      buildThreadDisplaySettingsReplyMarkup(mode),
+    );
+    await deps.answerCallbackQuery(callbackQueryId);
+    return true;
+  }
   if (data === "settings:list") {
     await updateTelegramSettingsMenuMessage(deps, deps.sectionRegistry);
     await deps.answerCallbackQuery(callbackQueryId);
@@ -692,6 +787,44 @@ export async function handleTelegramSettingsMenuCallbackAction(
       return true;
     }
   }
+  if (data === "settings:review:inactive-threads") {
+    if (!deps.reviewInactiveThreads) {
+      await deps.answerCallbackQuery(callbackQueryId, "Inactive tab review is unavailable.");
+      return true;
+    }
+    try {
+      const review = await deps.reviewInactiveThreads();
+      if (review.count === 0) {
+        await deps.answerCallbackQuery(callbackQueryId, "No proven inactive tabs.");
+      } else {
+        await deps.updateSettingsMessage(buildInactiveThreadReviewText(review.count),
+          buildInactiveThreadReviewReplyMarkup(review.operationId, !!deps.cleanInactiveThreads));
+        await deps.answerCallbackQuery(callbackQueryId, "Review prepared. No tabs were deleted.");
+      }
+    } catch {
+      await deps.answerCallbackQuery(callbackQueryId, "Could not safely review inactive tabs.");
+    }
+    return true;
+  }
+  if (data.startsWith("settings:clean:")) {
+    const operationId = data.slice("settings:clean:".length);
+    if (!/^thread-cleanup:[a-f0-9]{32}$/u.test(operationId) || !deps.cleanInactiveThreads) {
+      await deps.answerCallbackQuery(callbackQueryId, "Cleanup confirmation is unavailable or stale.");
+      return true;
+    }
+    try {
+      const result = await deps.cleanInactiveThreads(operationId);
+      await deps.answerCallbackQuery(callbackQueryId,
+        `Deleted: ${result.deleted}. Outcome unknown: ${result.outcomeUnknown}.` +
+      (result.blocked ? ` Blocked: ${result.blocked}.` : "") +
+      (result.recovery === "commit-ready" ? " Recovery: safe local commit pending." :
+        result.recovery === "deletion-outcome-unknown" ? " Recovery: deletion outcome unknown; no retry." :
+        result.recovery === "authority-blocked" ? " Recovery: cleanup authority unavailable." : ""));
+    } catch {
+      await deps.answerCallbackQuery(callbackQueryId, "Cleanup could not be safely completed.");
+    }
+    return true;
+  }
   if (
     data === "settings:set:automatic-thread-cleanup:on" ||
     data === "settings:set:automatic-thread-cleanup:off"
@@ -729,6 +862,7 @@ export function createTelegramSettingsMenuRuntime<
           isVoiceReplyModeConfigured: deps.isVoiceReplyModeConfigured,
           getTimeInjectionMode: deps.getTimeInjectionMode,
           isAutomaticThreadCleanupEnabled: deps.isAutomaticThreadCleanupEnabled,
+          getThreadDisplayMode: deps.getThreadDisplayMode,
           sendSettingsMenu: (state, text, replyMarkup) =>
             deps.sendInteractiveMessage(
               state.chatId,
@@ -752,6 +886,7 @@ export function createTelegramSettingsMenuRuntime<
           isVoiceReplyModeConfigured: deps.isVoiceReplyModeConfigured,
           getTimeInjectionMode: deps.getTimeInjectionMode,
           isAutomaticThreadCleanupEnabled: deps.isAutomaticThreadCleanupEnabled,
+          getThreadDisplayMode: deps.getThreadDisplayMode,
           updateSettingsMessage: (text, replyMarkup) =>
             deps.editInteractiveMessage(
               state.chatId,
@@ -795,12 +930,16 @@ export function createTelegramSettingsMenuRuntime<
         isVoiceReplyModeConfigured: deps.isVoiceReplyModeConfigured,
         getTimeInjectionMode: deps.getTimeInjectionMode,
         isAutomaticThreadCleanupEnabled: deps.isAutomaticThreadCleanupEnabled,
+        getThreadDisplayMode: deps.getThreadDisplayMode,
+        setThreadDisplayMode: deps.setThreadDisplayMode,
         setDraftPreviewsEnabled: deps.setDraftPreviewsEnabled,
         setAssistantRenderingMode: deps.setAssistantRenderingMode,
         setActivityVerbosity: deps.setActivityVerbosity,
         setVoiceReplyMode: deps.setVoiceReplyMode,
         setTimeInjectionMode: deps.setTimeInjectionMode,
         setAutomaticThreadCleanupEnabled: deps.setAutomaticThreadCleanupEnabled,
+        ...(deps.reviewInactiveThreads ? { reviewInactiveThreads: deps.reviewInactiveThreads } : {}),
+        ...(deps.cleanInactiveThreads ? { cleanInactiveThreads: deps.cleanInactiveThreads } : {}),
         updateSettingsMessage: (text, replyMarkup) =>
           deps.editInteractiveMessage(
             state.chatId,

package/node_modules/@llblab/pi-telegram/lib/outbound-attachments.ts

@@ -21,7 +21,7 @@ import {
   TELEGRAM_MESSAGE_PROMPT_SNIPPET,
 } from "./prompts.ts";
 import {
-  buildTelegramMultipartReplyParameters,
+  withTelegramReplyParameters,
   normalizeTelegramNativeMarkdown,
 } from "./replies.ts";
 import {
@@ -99,6 +99,11 @@ export interface TelegramOutboundMessageToolRegistrationDeps extends TelegramOut
     markdown: string,
     options?: { replyMarkup?: unknown; target?: TelegramTarget },
   ) => Promise<number | undefined>;
+  sendChannelMarkdownMessage?: (
+    channel: number | string,
+    markdown: string,
+    options: { operationId: string; replyMarkup?: unknown },
+  ) => Promise<number | undefined>;
 }
 
 export interface TelegramQueuedOutboundAttachmentView {
@@ -177,7 +182,7 @@ export function planTelegramRichOutboundAttachment(options: {
   if (!mediaType) return undefined;
   const mediaId = "artifact";
   const richMessage = {
-    markdown: `${normalizeTelegramNativeMarkdown(options.markdown)}\n\n![](tg://${mediaType}?id=${mediaId})`,
+    markdown: `![](tg://${mediaType}?id=${mediaId})\n\n${normalizeTelegramNativeMarkdown(options.markdown)}`,
     media: [
       {
         id: mediaId,
@@ -187,20 +192,11 @@ export function planTelegramRichOutboundAttachment(options: {
         },
       },
     ],
-    skip_entity_detection: true,
   };
-  const replyParameters =
-    options.turn.replyToMessageId > 0
-      ? JSON.stringify({
-          message_id: options.turn.replyToMessageId,
-          allow_sending_without_reply: true,
-        })
-      : undefined;
   return {
     method: "sendRichMessage",
     fields: {
       chat_id: String(options.turn.chatId),
-      ...(replyParameters ? { reply_parameters: replyParameters } : {}),
       ...getTelegramMultipartTargetFields(options.turn.target),
       rich_message: JSON.stringify(richMessage),
       ...(options.replyMarkup
@@ -230,12 +226,15 @@ export function createTelegramRichOutboundAttachmentSender(
     });
     if (!plan) return false;
     try {
-      const result = await deps.sendMultipart(
-        plan.method,
-        plan.fields,
-        plan.fileField,
-        plan.filePath,
-        plan.fileName,
+      const result = await withTelegramReplyParameters(
+        turn.chatId, turn.replyToMessageId, turn.target,
+        (replyParameters) => deps.sendMultipart(
+          plan.method,
+          { ...plan.fields, ...(replyParameters ? { reply_parameters: JSON.stringify(replyParameters) } : {}) },
+          plan.fileField,
+          plan.filePath,
+          plan.fileName,
+        ),
       );
       const messageId =
         result && typeof result === "object" &&
@@ -352,7 +351,7 @@ function formatTelegramOutboundAttachmentToolResultText(
   return ["", `${verb} ${count} Telegram attachment(s).`].join("\n");
 }
 
-function formatTelegramOutboundMessageToolResultText(chatId: number): string {
+function formatTelegramOutboundMessageToolResultText(chatId: number | string): string {
   return ["", `Sent Telegram message to ${chatId}.`].join("\n");
 }
 
@@ -518,19 +517,25 @@ export function registerTelegramOutboundMessageTool(
     name: "telegram_message",
     label: "Telegram Message",
     description:
-      "Send a Markdown text message directly to the paired/default Telegram chat or an explicit chat_id. Hidden telegram_button comments in the text become attached inline prompt buttons.",
+      "Send Markdown text directly to the paired/default Telegram chat, an exact channel chat_id, or an explicit live target. Channel posting requires Telegram-granted bot permission. Hidden telegram_button comments become inline prompt buttons.",
     promptSnippet: TELEGRAM_MESSAGE_PROMPT_SNIPPET,
     promptGuidelines: [...TELEGRAM_MESSAGE_PROMPT_GUIDELINES],
     parameters: Type.Object({
       text: Type.String({ description: "Message text to send" }),
       chat_id: Type.Optional(
-        Type.Number({ description: "Optional Telegram chat id" }),
+        Type.Union([
+          Type.Number(),
+          Type.String({ pattern: "^@[A-Za-z0-9_]{5,32}$" }),
+        ], { description: "Optional exact Telegram chat id or public channel @username" }),
       ),
       thread_id: Type.Optional(
         Type.Number({
           description: "Optional Telegram topic thread id with chat_id",
         }),
       ),
+      channel: Type.Optional(Type.Boolean({
+        description: "Set true only when a numeric chat_id is explicitly intended as a channel",
+      })),
       thread: Type.Optional(
         Type.Union([Type.String(), Type.Number()], {
           description:
@@ -538,10 +543,12 @@ export function registerTelegramOutboundMessageTool(
         }),
       ),
     }),
-    async execute(_toolCallId, params) {
+    async execute(toolCallId, params) {
       try {
         return await sendTelegramOutboundMessage({
           text: params.text,
+          operationId: toolCallId,
+          channel: params.channel,
           chatId: params.chat_id,
           threadId: params.thread_id,
           agentThread: params.thread,
@@ -553,10 +560,14 @@ export function registerTelegramOutboundMessageTool(
           canSendDirect: deps.canSendDirect,
           planMessage: deps.planMessage,
           sendMarkdownMessage: deps.sendMarkdownMessage,
+          sendChannelMarkdownMessage: deps.sendChannelMarkdownMessage,
         });
       } catch (error) {
-        deps.recordRuntimeEvent?.("message", error, { phase: "direct" });
-        throw formatTelegramOutboundToolError(error);
+        const reportableError = typeof params.chat_id === "string" || params.channel === true
+          ? new Error("Telegram channel publication failed; inspect the retained local record before retrying.")
+          : error;
+        deps.recordRuntimeEvent?.("message", reportableError, { phase: "direct" });
+        throw formatTelegramOutboundToolError(reportableError);
       }
     },
   });
@@ -760,7 +771,9 @@ export async function deliverTelegramGuestCachedAttachment(options: {
 
 export async function sendTelegramOutboundMessage(options: {
   text: string;
-  chatId?: number;
+  operationId?: string;
+  channel?: boolean;
+  chatId?: number | string;
   threadId?: number;
   agentThread?: string | number;
   target?: TelegramTarget;
@@ -780,12 +793,35 @@ export async function sendTelegramOutboundMessage(options: {
     markdown: string,
     options?: { replyMarkup?: unknown; target?: TelegramTarget },
   ) => Promise<number | undefined>;
+  sendChannelMarkdownMessage?: (
+    channel: number | string,
+    markdown: string,
+    options: { operationId: string; replyMarkup?: unknown },
+  ) => Promise<number | undefined>;
 }): Promise<{
   content: Array<{ type: "text"; text: string }>;
-  details: { chatId: number; messageId?: number };
+  details: { chatId: number | string; messageId?: number };
 }> {
   assertTelegramDirectDeliveryAllowed(options.canSendDirect);
   const activeTurn = options.getActiveTurn?.();
+  if (typeof options.chatId === "string" || options.channel === true) {
+    if (!((typeof options.chatId === "string" && /^@[A-Za-z0-9_]{5,32}$/u.test(options.chatId)) ||
+        (typeof options.chatId === "number" && Number.isSafeInteger(options.chatId) && options.chatId < 0)) ||
+        options.threadId !== undefined ||
+        options.target !== undefined || options.agentThread !== undefined) {
+      throw new Error("Telegram channel delivery requires one exact @username or negative numeric channel ID without a thread target.");
+    }
+    if (!options.sendChannelMarkdownMessage || !options.operationId) {
+      throw new Error("Telegram channel delivery requires direct leader transport ownership and operation identity.");
+    }
+    const plan = options.planMessage(options.text);
+    const messageId = await options.sendChannelMarkdownMessage(
+      options.chatId, plan.markdown, { operationId: options.operationId,
+        replyMarkup: plan.replyMarkup });
+    return { content: [{ type: "text",
+      text: formatTelegramOutboundMessageToolResultText(options.chatId) }],
+    details: { chatId: options.chatId, messageId } };
+  }
   const requestedAgentSelector: TelegramBusAgentTargetSelector | undefined =
     options.agentThread !== undefined
       ? typeof options.agentThread === "number"
@@ -964,21 +1000,19 @@ export async function sendQueuedTelegramOutboundAttachments(
       const isPhoto = isTelegramOutboundPhotoAttachmentPath(attachment.path);
       const method = isPhoto ? "sendPhoto" : "sendDocument";
       const fieldName = isPhoto ? "photo" : "document";
-      const replyParameters = buildTelegramMultipartReplyParameters(
-        turn.chatId,
-        turn.replyToMessageId,
-        turn.target,
-      );
-      await deps.sendMultipart(
-        method,
-        {
-          chat_id: String(turn.chatId),
-          ...(replyParameters ? { reply_parameters: replyParameters } : {}),
-          ...getTelegramMultipartTargetFields(turn.target),
-        },
-        fieldName,
-        attachment.path,
-        attachment.fileName,
+      await withTelegramReplyParameters(
+        turn.chatId, turn.replyToMessageId, turn.target,
+        (replyParameters) => deps.sendMultipart(
+          method,
+          {
+            chat_id: String(turn.chatId),
+            ...(replyParameters ? { reply_parameters: JSON.stringify(replyParameters) } : {}),
+            ...getTelegramMultipartTargetFields(turn.target),
+          },
+          fieldName,
+          attachment.path,
+          attachment.fileName,
+        ),
       );
     } catch (error) {
       if (deps.isDeliveryActive?.() === false) return;