@llblab/pi-kit 0.6.0 → 0.7.1

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;
 }
 
@@ -1139,6 +1144,7 @@ export interface TelegramLockedPollingRuntimeDeps<
 > {
   lock: TelegramLockRuntime<TContext>;
   hasBotToken: () => boolean;
+  getBotTokenDiagnostic?: () => string | undefined;
   canStartPolling?: (ctx: TContext) => boolean;
   isContextCurrent?: (ctx: TContext) => boolean;
   formatStartBlockedMessage?: (ctx: TContext) => string;
@@ -1151,6 +1157,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 +1208,7 @@ export function createTelegramLockedPollingRuntime<
     stopOwnershipWatcher();
     if (sessionAutoStartRun) {
       await sessionAutoStartRun;
+      deps.stopFollowerRegistration?.();
     }
     if (ownershipStop) {
       await ownershipStop;
@@ -1295,7 +1306,11 @@ export function createTelegramLockedPollingRuntime<
   return {
     start: async (ctx, options = {}) => {
       if (!deps.hasBotToken()) {
-        return { ok: false, message: "Telegram bot is not configured." };
+        return {
+          ok: false,
+          message:
+            deps.getBotTokenDiagnostic?.() ?? "Telegram bot is not configured.",
+        };
       }
       if (!canStartPolling(ctx)) {
         return { ok: false, message: formatStartBlockedMessage(ctx) };
@@ -1452,10 +1467,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 +1485,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 +1540,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,9 +197,35 @@ 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>`,
@@ -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

@@ -13,6 +13,10 @@ import type {
   TelegramBusAgentMessage,
   TelegramBusAgentTargetSelector,
 } from "./bus.ts";
+import {
+  isTelegramChannelPostValidationError,
+  TelegramChannelPostValidationError,
+} from "./channel-posts.ts";
 import type { ExtensionAPI } from "./pi.ts";
 import {
   TELEGRAM_ATTACH_PROMPT_GUIDELINES,
@@ -99,6 +103,17 @@ 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>;
+  sendChannelMediaMessage?: (
+    channel: number | string,
+    mediaPath: string,
+    markdown: string,
+    options: { operationId: string; replyMarkup?: unknown },
+  ) => Promise<number | undefined>;
 }
 
 export interface TelegramQueuedOutboundAttachmentView {
@@ -177,7 +192,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,7 +202,6 @@ export function planTelegramRichOutboundAttachment(options: {
         },
       },
     ],
-    skip_entity_detection: true,
   };
   return {
     method: "sendRichMessage",
@@ -347,7 +361,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");
 }
 
@@ -513,19 +527,32 @@ 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 delivery supports one optional local photo or video upload with the text as its caption. 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" }),
+      media: Type.Optional(
+        Type.String({
+          minLength: 1,
+          description:
+            "Local single-file channel upload: .jpg/.jpeg/.png/.webp photo or .mp4 video; the text becomes its caption (max 1024 characters). Albums and other media types are rejected.",
+        }),
+      ),
       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:
@@ -533,10 +560,13 @@ export function registerTelegramOutboundMessageTool(
         }),
       ),
     }),
-    async execute(_toolCallId, params) {
+    async execute(toolCallId, params) {
       try {
         return await sendTelegramOutboundMessage({
           text: params.text,
+          media: params.media,
+          operationId: toolCallId,
+          channel: params.channel,
           chatId: params.chat_id,
           threadId: params.thread_id,
           agentThread: params.thread,
@@ -548,10 +578,17 @@ export function registerTelegramOutboundMessageTool(
           canSendDirect: deps.canSendDirect,
           planMessage: deps.planMessage,
           sendMarkdownMessage: deps.sendMarkdownMessage,
+          sendChannelMarkdownMessage: deps.sendChannelMarkdownMessage,
+          sendChannelMediaMessage: deps.sendChannelMediaMessage,
         });
       } catch (error) {
-        deps.recordRuntimeEvent?.("message", error, { phase: "direct" });
-        throw formatTelegramOutboundToolError(error);
+        const isChannelTarget = typeof params.chat_id === "string" || params.channel === true;
+        const reportableError = isChannelTarget &&
+            !isTelegramChannelPostValidationError(error)
+          ? new Error("Telegram channel publication failed; inspect the retained local record before retrying.")
+          : error;
+        deps.recordRuntimeEvent?.("message", reportableError, { phase: "direct" });
+        throw formatTelegramOutboundToolError(reportableError);
       }
     },
   });
@@ -755,7 +792,10 @@ export async function deliverTelegramGuestCachedAttachment(options: {
 
 export async function sendTelegramOutboundMessage(options: {
   text: string;
-  chatId?: number;
+  media?: string;
+  operationId?: string;
+  channel?: boolean;
+  chatId?: number | string;
   threadId?: number;
   agentThread?: string | number;
   target?: TelegramTarget;
@@ -775,12 +815,59 @@ 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>;
+  sendChannelMediaMessage?: (
+    channel: number | string,
+    mediaPath: 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.");
+    }
+    const plan = options.planMessage(options.text);
+    if (options.media !== undefined) {
+      if (!options.sendChannelMediaMessage || !options.operationId) {
+        throw new TelegramChannelPostValidationError(
+          "Telegram channel media delivery requires direct leader transport ownership and operation identity.",
+        );
+      }
+      const messageId = await options.sendChannelMediaMessage(
+        options.chatId, options.media, plan.markdown,
+        { operationId: options.operationId, replyMarkup: plan.replyMarkup });
+      return { content: [{ type: "text",
+        text: formatTelegramOutboundMessageToolResultText(options.chatId) }],
+      details: { chatId: options.chatId, messageId } };
+    }
+    if (!options.sendChannelMarkdownMessage || !options.operationId) {
+      throw new Error("Telegram channel delivery requires direct leader transport ownership and operation identity.");
+    }
+    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 } };
+  }
+  if (options.media !== undefined) {
+    throw new TelegramChannelPostValidationError(
+      "telegram_message media uploads require channel delivery with an exact @username or negative numeric channel ID and channel: true.",
+    );
+  }
   const requestedAgentSelector: TelegramBusAgentTargetSelector | undefined =
     options.agentThread !== undefined
       ? typeof options.agentThread === "number"

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

@@ -87,6 +87,35 @@ export function getTelegramDiagnosticsDisplayPaths(profileName?: string): {
   };
 }
 
+/** Durable Workspace admission ledger (<agentDir>/tmp/telegram/workspace-admission[.<profile>].json). */
+export function resolveTelegramWorkspaceAdmissionPath(
+  agentDir = resolveAgentDir(),
+  profileName?: string,
+): string {
+  return resolveTelegramProfileTempFilePath(
+    "workspace-admission",
+    "json",
+    agentDir,
+    profileName,
+  );
+}
+
+/** Durable inactive Thread cleanup work-set journal. */
+export function resolveTelegramThreadCleanupWorkPath(
+  agentDir = resolveAgentDir(),
+  profileName?: string,
+): string {
+  return resolveTelegramProfileTempFilePath("thread-cleanup", "json", agentDir, profileName);
+}
+
+/** Durable agent-authored channel post journal. */
+export function resolveTelegramChannelPostJournalPath(
+  agentDir = resolveAgentDir(),
+  profileName?: string,
+): string {
+  return resolveTelegramProfileTempFilePath("channel-posts", "json", agentDir, profileName);
+}
+
 /** Durable inbound update journal (<agentDir>/tmp/telegram/inbox[.<profile>].json). */
 export function resolveTelegramUpdateJournalPath(
   agentDir = resolveAgentDir(),