@llblab/pi-kit 0.6.0 → 0.7.0

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

@@ -280,11 +280,12 @@ export type TelegramDurablePollingRuntimeAssemblyDeps<
   "appendUpdateBatch" | "getJournalEntryCount" | "signalUpdateWorker"
 > & {
   canStart?: (ctx: TContext) => boolean;
+  prepareUpdateBatch?: (updates: readonly TUpdate[]) => void;
   journal: {
     appendBatch: (
       updates: readonly TUpdate[],
       acceptedThroughUpdateId?: number,
-    ) => MaybePromise<unknown>;
+    ) => { nonExcludedUpdateIds: readonly number[] };
     getAcceptedThroughUpdateId: () => number | undefined;
     prepareCursorCutover?: () => MaybePromise<void>;
     getEntryCount: () => number;
@@ -303,7 +304,30 @@ export function createTelegramDurablePollingRuntimeAssembly<
 ): TelegramDurablePollingRuntimeAssembly<TContext> {
   const controller = createTelegramPollingControllerRuntime({
     ...deps,
-    appendUpdateBatch: deps.journal.appendBatch,
+    appendUpdateBatch(updates, cursor) {
+      const result = deps.journal.appendBatch(updates, cursor);
+      if (!deps.prepareUpdateBatch) return result;
+      // No await: an already-draining worker must not observe the new batch before preparation.
+      try {
+        const included = new Set(result.nonExcludedUpdateIds);
+        let batch: TUpdate[] = [];
+        for (const update of updates) {
+          if (included.has(update.update_id)) batch.push(update);
+          else if (batch.length > 0) {
+            deps.prepareUpdateBatch(batch);
+            batch = [];
+          }
+        }
+        if (batch.length > 0) deps.prepareUpdateBatch(batch);
+      } catch (error) {
+        try {
+          deps.recordRuntimeEvent?.("polling", error, { phase: "batch-preparation", updateCount: updates.length });
+        } catch {
+          // Already-published input must still reach the worker if diagnostics fail.
+        }
+      }
+      return result;
+    },
     getAcceptedThroughUpdateId: deps.journal.getAcceptedThroughUpdateId,
     getJournalEntryCount: deps.journal.getEntryCount,
     signalUpdateWorker: deps.journal.signalWorker,
@@ -393,7 +417,6 @@ export function createTelegramPollingControllerRuntime<
       getAcceptedThroughUpdateId: deps.getAcceptedThroughUpdateId,
       getJournalEntryCount: deps.getJournalEntryCount,
       signalUpdateWorker: deps.signalUpdateWorker,
-      prepareUpdateBatch: deps.prepareUpdateBatch,
       updateStatus: deps.updateStatus,
       sleep: deps.sleep,
       onPhaseChange(phase, currentUpdateId) {
@@ -651,6 +674,7 @@ export interface TelegramThreadCapabilityRuntimeDeps<
   getPollingStartedWithTelegramBus: () => boolean;
   setPollingStartedWithTelegramBus: (started: boolean) => void;
   setTopicModeUnavailable: (unavailable: boolean) => void;
+  suspendLiveThreadTarget?: () => void;
   stopFollowerRegistration: () => void;
   startClassicPolling: (ctx: TContext) => MaybePromise<void>;
   stopClassicPolling: () => MaybePromise<void>;
@@ -682,6 +706,8 @@ export interface TelegramThreadCapabilityStateRuntime {
   isBusRuntimeEnabled(): boolean;
   shouldForceFreshLeaderThread(): boolean;
   setForceFreshLeaderThread(forceFresh: boolean): void;
+  getRequestedThreadName(): string | undefined;
+  setRequestedThreadName(threadName: string | undefined): void;
 }
 
 export type TelegramThreadTargetObservationHandler<TContext> = (
@@ -715,6 +741,10 @@ export interface TelegramThreadAwarePollingPorts<TContext, TOwner> {
     ctx: TContext,
     owner: TOwner,
   ) => Promise<boolean | undefined>;
+  restoreFollowerWithOwner: (
+    ctx: TContext,
+    owner: TOwner,
+  ) => Promise<boolean | undefined>;
   stopFollowerRegistration: () => void;
 }
 
@@ -738,6 +768,11 @@ export interface TelegramThreadAwarePollingDeps<
     ctx: TContext,
     owner: TOwner,
   ) => Promise<boolean | undefined>;
+  restoreFollowerWithLeader?: (
+    ctx: TContext,
+    owner: TOwner,
+  ) => Promise<boolean | undefined>;
+  hasRememberedWorkspaceBinding?: (ctx: TContext) => boolean;
   stopFollowerRegistration: () => void;
 }
 
@@ -760,6 +795,12 @@ export interface TelegramThreadCapabilityOrchestrationDeps<
     ctx: TContext,
     owner: TOwner,
   ) => Promise<boolean | undefined>;
+  restoreFollowerWithLeader?: (
+    ctx: TContext,
+    owner: TOwner,
+  ) => Promise<boolean | undefined>;
+  hasRememberedWorkspaceBinding?: (ctx: TContext) => boolean;
+  suspendLiveThreadTarget?: () => void;
   stopFollowerRegistration: () => void;
   isTopicModeUnavailableError: (error: unknown) => boolean;
   updateStatus: (ctx: TContext) => void;
@@ -780,6 +821,7 @@ export function createTelegramThreadCapabilityStateRuntime(): TelegramThreadCapa
   let busPollingStarted = false;
   let topicModeUnavailable = false;
   let forceFreshLeaderThread = false;
+  let requestedThreadName: string | undefined;
   return {
     isBusPollingStarted: () => busPollingStarted,
     setBusPollingStarted(started) {
@@ -794,6 +836,10 @@ export function createTelegramThreadCapabilityStateRuntime(): TelegramThreadCapa
     setForceFreshLeaderThread(forceFresh) {
       forceFreshLeaderThread = forceFresh;
     },
+    getRequestedThreadName: () => requestedThreadName,
+    setRequestedThreadName(threadName) {
+      requestedThreadName = threadName;
+    },
   };
 }
 
@@ -818,6 +864,7 @@ export function createTelegramThreadCapabilityOrchestration<TContext, TOwner>(
     getPollingStartedWithTelegramBus: deps.state.isBusPollingStarted,
     setPollingStartedWithTelegramBus: deps.state.setBusPollingStarted,
     setTopicModeUnavailable: deps.state.setTopicModeUnavailable,
+    suspendLiveThreadTarget: deps.suspendLiveThreadTarget,
     stopFollowerRegistration: deps.stopFollowerRegistration,
     startClassicPolling: deps.startClassicPolling,
     stopClassicPolling: deps.stopClassicPolling,
@@ -850,6 +897,8 @@ export function createTelegramThreadCapabilityOrchestration<TContext, TOwner>(
       startLeaderHealth: deps.startLeaderHealth,
       stopLeaderHealth: deps.stopLeaderHealth,
       registerFollowerWithLeader: deps.registerFollowerWithLeader,
+      restoreFollowerWithLeader: deps.restoreFollowerWithLeader,
+      hasRememberedWorkspaceBinding: deps.hasRememberedWorkspaceBinding,
       stopFollowerRegistration: deps.stopFollowerRegistration,
       recordEvent: deps.recordEvent,
       setTopicModeUnavailable: deps.state.setTopicModeUnavailable,
@@ -958,14 +1007,16 @@ export async function applyTelegramThreadCapability<TContext>(
     if (!isCurrent()) return;
     deps.setTopicModeUnavailable(true);
     deps.stopFollowerRegistration();
+    const hadLiveThreadTransport = deps.getPollingStartedWithTelegramBus();
     if (
-      deps.getPollingStartedWithTelegramBus() ||
+      hadLiveThreadTransport ||
       hasTelegramClassicRestoreFailure(previousBotState)
     ) {
       deps.stopLeaderHealth();
       await deps.stopBusPolling();
       if (!isCurrent()) return;
       deps.setPollingStartedWithTelegramBus(false);
+      if (hadLiveThreadTransport) deps.suspendLiveThreadTarget?.();
       try {
         await deps.startClassicPolling(ctx);
         if (!isCurrent()) return;
@@ -1110,24 +1161,34 @@ export function createTelegramThreadAwarePollingPorts<TContext, TOwner>(
     }
     await deps.stopClassicPolling();
   };
-  const registerFollowerWithOwner = async (
-    ctx: TContext,
-    owner: TOwner,
-  ): Promise<boolean | undefined> => {
+  const refreshFollowerState = async (): Promise<boolean> => {
     if (deps.topicTargetStore.refresh) {
       await deps.topicTargetStore.refresh();
     } else {
       await deps.topicTargetStore.load();
     }
-    if (deps.topicTargetStore.getBotState().threadMode !== "enabled") {
-      return undefined;
-    }
+    return deps.topicTargetStore.getBotState().threadMode === "enabled";
+  };
+  const registerFollowerWithOwner = async (
+    ctx: TContext,
+    owner: TOwner,
+  ): Promise<boolean | undefined> => {
+    if (!(await refreshFollowerState())) return undefined;
     return deps.registerFollowerWithLeader(ctx, owner);
   };
+  const restoreFollowerWithOwner = async (
+    ctx: TContext,
+    owner: TOwner,
+  ): Promise<boolean | undefined> => {
+    if (!(await refreshFollowerState())) return undefined;
+    if (!deps.hasRememberedWorkspaceBinding?.(ctx)) return undefined;
+    return deps.restoreFollowerWithLeader?.(ctx, owner);
+  };
   return {
     startPolling,
     stopPolling,
     registerFollowerWithOwner,
+    restoreFollowerWithOwner,
     stopFollowerRegistration: deps.stopFollowerRegistration,
   };
 }
@@ -1179,9 +1240,9 @@ export function createTelegramThreadCapabilityMonitor<TContext>(
   let consecutiveDisabledProbes = 0;
   const stop = (): void => {
     generation += 1;
-    deps.lifecycle?.invalidate();
     if (interval) clearInterval(interval);
     interval = undefined;
+    deps.lifecycle?.invalidate();
   };
   const check = (ctx: TContext): void => {
     if (transitionPromise || !canProbeTelegramThreadCapability(ctx, deps)) {
@@ -1276,8 +1337,19 @@ export function createTelegramThreadCapabilityMonitor<TContext>(
   return {
     start(ctx) {
       stop();
+      const expectedGeneration = generation;
       interval = setInterval(() => {
-        check(ctx);
+        if (generation !== expectedGeneration) return;
+        try {
+          check(ctx);
+        } catch (error) {
+          try { stop(); } catch { /* Timer shutdown must not escape the callback. */ }
+          try {
+            deps.recordEvent("bus", error, { phase: "capability-monitor" });
+          } catch {
+            // Monitor diagnostics cannot create an uncaught interval exception.
+          }
+        }
       }, intervalMs);
       interval.unref?.();
     },
@@ -1416,7 +1488,6 @@ export interface TelegramPollLoopDeps<
   getAcceptedThroughUpdateId?: () => number | undefined;
   getJournalEntryCount: () => number;
   signalUpdateWorker: () => void;
-  prepareUpdateBatch?: (updates: readonly TUpdate[]) => void;
   onErrorStatus: (message: string) => void;
   onStatusReset: () => void;
   sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
@@ -1446,7 +1517,6 @@ export interface TelegramPollLoopRunnerDeps<
   getAcceptedThroughUpdateId?: () => number | undefined;
   getJournalEntryCount: () => number;
   signalUpdateWorker: () => void;
-  prepareUpdateBatch?: (updates: readonly TUpdate[]) => void;
   updateStatus: (ctx: TContext, message?: string) => void;
   sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
   onPhaseChange?: (
@@ -1501,7 +1571,6 @@ export function createTelegramPollLoopRunner<
       getAcceptedThroughUpdateId: deps.getAcceptedThroughUpdateId,
       getJournalEntryCount: deps.getJournalEntryCount,
       signalUpdateWorker: deps.signalUpdateWorker,
-      prepareUpdateBatch: deps.prepareUpdateBatch,
       onErrorStatus: (message) => {
         updateTelegramPollingStatusSafely(deps.updateStatus, ctx, {
           message,
@@ -1702,7 +1771,6 @@ export async function runTelegramPollLoop<
       reportTelegramPollingPhase(deps, "long-poll");
       const updates = await requestTelegramUpdatesWithinBudget(deps, request);
       reportTelegramPollingResponse(deps, updates.length);
-      deps.prepareUpdateBatch?.(updates);
       consecutiveGetUpdatesConflicts = 0;
       currentUpdateId = updates[0]?.update_id;
       await admitTelegramPollingUpdateBatch({

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

@@ -14,7 +14,7 @@ export const TELEGRAM_DISCONNECTED_CONTEXT_MESSAGE =
 
 const LOCAL_SYSTEM_PROMPT_SUFFIX = `
 
-${TELEGRAM_CONNECTED_CONTEXT_MESSAGE} For Telegram work, consult bundled Skills in routing order: \`telegram-bridge\` for the transport and turn protocol, \`generated-control-surface\` when contextual controls materially shorten feedback, then \`generative-apps\` when the interaction warrants a reusable deterministic app. Load a Skill only if its instructions are not already present in the current context. Do not use Telegram-specific features from unrelated local/TUI prompts.`;
+${TELEGRAM_CONNECTED_CONTEXT_MESSAGE} For Telegram work, consult bundled Skills in routing order: \`telegram-bridge\` for the transport and turn protocol, \`show-me\` when a user needs a truthful visual explanation of work or behavior, \`generated-control-surface\` when contextual controls materially shorten feedback, then \`generative-apps\` when the interaction warrants a reusable deterministic app. Load a Skill only if its instructions are not already present in the current context. Do not use Telegram-specific features from unrelated local/TUI prompts.`;
 
 const TELEGRAM_TURN_SYSTEM_PROMPT_SUFFIX = `
 
@@ -28,9 +28,10 @@ export const TELEGRAM_ATTACH_PROMPT_GUIDELINES = [
   "For an explicit thread target, provide chat_id plus thread_id; registered multi-instance followers default to their assigned thread target.",
 ] as const;
 export const TELEGRAM_MESSAGE_PROMPT_SNIPPET =
-  "Send direct Telegram Markdown text when the user explicitly asks for Telegram delivery outside the normal reply flow.";
+  "Send direct Telegram Markdown text when the user explicitly asks for Telegram delivery to a concrete chat, channel, or live Pi Thread outside the normal reply flow.";
 export const TELEGRAM_MESSAGE_PROMPT_GUIDELINES = [
   "Use telegram_message only when the user explicitly asks to send a message to Telegram from the local/TUI side, or names a concrete Telegram delivery target.",
+  "For an explicitly requested channel post, pass its exact numeric id or public @username as chat_id; no local channel registry is required, and Telegram remains the authority on the bot's posting permission.",
   "For a live Pi thread target, provide thread as its case-insensitive name or numeric id; the bridge sends visibly and admits one attributed turn to that live instance. Unknown, ambiguous, same, or offline targets fail before sending.",
   "Add buttons by embedding the same top-level telegram_button HTML comments used in normal Telegram replies; Telegram does not support standalone buttons.",
   "During an active Telegram turn, omit telegram_message for the current target and answer normally; use thread only when the user requests delivery to a different live Pi thread.",
@@ -48,6 +49,8 @@ const TELEGRAM_TOOL_METADATA_LINES = Object.fromEntries(
 const TELEGRAM_MODEL_CONTEXT_TOOL_NAMES = new Set([
   "telegram_attach",
   "telegram_bind",
+  "telegram_channel_post",
+  "telegram_channel_posts",
   "telegram_message",
 ]);
 const TELEGRAM_MODEL_CONTEXT_MEMORY_KEY = Symbol.for(

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

@@ -1527,7 +1527,7 @@ export interface TelegramAgentEndRuntimeDeps<
     chatId: number,
     replyToMessageId: number,
     text: string,
-    options?: { target?: TelegramQueueTarget },
+    options?: { target?: TelegramQueueTarget; parseMode?: "HTML" },
   ) => Promise<unknown>;
   sendQueuedAttachments: (
     turn: TTurn,
@@ -1908,23 +1908,37 @@ export async function handleTelegramAgentEndRuntime<
   const deliverActiveTurn = async () => {
     await deps.waitForActivityIdle?.();
     if (!isDeliveryActive()) return;
-    if (endPlan.shouldClearPreview || (!finalText && hasOutboundArtifacts)) {
+    let previewCleared = false;
+    const clearTurnPreview = async () => {
+      if (previewCleared) return;
       await clearPreview?.();
+      previewCleared = true;
+    };
+    if (endPlan.shouldClearPreview || (!finalText && hasOutboundArtifacts)) {
+      await clearTurnPreview();
       if (!isDeliveryActive()) return;
     }
     if (endPlan.shouldSendErrorMessage) {
+      const errorMessage = assistant.errorMessage ||
+        "Telegram bridge: Pi failed while processing the request.";
+      const isOperationAborted = errorMessage.trim().replace(/\.$/, "") ===
+        "This operation was aborted";
       await deps.sendTextReply(
         turn.chatId,
         turn.replyToMessageId,
-        assistant.errorMessage ||
-          "Telegram bridge: Pi failed while processing the request.",
-        { target: turn.target },
+        isOperationAborted
+          ? "<b>⏹️ This operation was aborted.</b>"
+          : errorMessage,
+        {
+          target: turn.target,
+          ...(isOperationAborted ? { parseMode: "HTML" as const } : {}),
+        },
       );
       if (!isDeliveryActive()) return;
       if (endPlan.shouldDispatchNext) deps.dispatchNextQueuedTelegramTurn();
       return;
     }
-    if (finalText) setPreviewPendingText(finalText);
+    if (finalText && turn.queuedAttachments.length === 0) setPreviewPendingText(finalText);
 
     if (!isDeliveryActive()) return;
     let richAttachmentDelivered = false;
@@ -1942,7 +1956,7 @@ export async function handleTelegramAgentEndRuntime<
         );
         if (!isDeliveryActive()) return;
         if (richAttachmentDelivered) {
-          await clearPreview?.();
+          await clearTurnPreview();
           if (!isDeliveryActive()) return;
           setPreviewPendingText("");
         }
@@ -1957,24 +1971,42 @@ export async function handleTelegramAgentEndRuntime<
       }
     }
     if (!isDeliveryActive()) return;
+    let queuedAttachmentsDelivered = false;
+    if (!richAttachmentDelivered && turn.queuedAttachments.length > 0) {
+      await clearTurnPreview();
+      if (!isDeliveryActive()) return;
+      setPreviewPendingText("");
+      await deps.sendQueuedAttachments(turn, { isDeliveryActive });
+      if (!isDeliveryActive()) return;
+      queuedAttachmentsDelivered = true;
+    }
     if (!richAttachmentDelivered && endPlan.kind === "text" && finalText) {
       try {
-        const finalized = await finalizeMarkdownPreview(
-          turn.chatId,
-          finalText,
-          turn.replyToMessageId,
-          { replyMarkup, target: turn.target },
-        );
-        if (!isDeliveryActive()) return;
-        if (!finalized) {
-          await clearPreview?.();
-          if (!isDeliveryActive()) return;
+        if (queuedAttachmentsDelivered) {
           await deps.sendMarkdownReply(
             turn.chatId,
             turn.replyToMessageId,
             finalText,
             { replyMarkup, target: turn.target },
           );
+        } else {
+          const finalized = await finalizeMarkdownPreview(
+            turn.chatId,
+            finalText,
+            turn.replyToMessageId,
+            { replyMarkup, target: turn.target },
+          );
+          if (!isDeliveryActive()) return;
+          if (!finalized) {
+            await clearTurnPreview();
+            if (!isDeliveryActive()) return;
+            await deps.sendMarkdownReply(
+              turn.chatId,
+              turn.replyToMessageId,
+              finalText,
+              { replyMarkup, target: turn.target },
+            );
+          }
         }
         if (!isDeliveryActive()) return;
         setPreviewPendingText("");
@@ -2041,7 +2073,9 @@ export async function handleTelegramAgentEndRuntime<
       );
     }
     if (!isDeliveryActive()) return;
-    if (!richAttachmentDelivered) await deps.sendQueuedAttachments(turn, { isDeliveryActive });
+    if (!richAttachmentDelivered && !queuedAttachmentsDelivered) {
+      await deps.sendQueuedAttachments(turn, { isDeliveryActive });
+    }
     if (!isDeliveryActive()) return;
     if (endPlan.shouldDispatchNext) deps.dispatchNextQueuedTelegramTurn();
   };

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

@@ -672,7 +672,7 @@ export async function sendTelegramNativeMarkdownReply<TReplyMarkup = unknown>(
       chatId, index === 0 ? replyToMessageId : undefined, options?.target,
       (replyParameters) => deps.sendRichMessage({
         chat_id: chatId,
-        rich_message: { markdown: chunk, skip_entity_detection: true },
+        rich_message: { markdown: chunk },
         reply_markup:
           index === chunks.length - 1 ? options?.replyMarkup : undefined,
         ...(replyParameters ? { reply_parameters: replyParameters } : {}),
@@ -894,7 +894,7 @@ export function createGuestMarkdownReplySender(deps: {
   return async (guestQueryId: string, markdown: string) => {
     const [richMarkdown = markdown] = splitTelegramNativeMarkdown(markdown);
     await deps.answerGuestQuery(guestQueryId, undefined, {
-      richMessage: { markdown: richMarkdown, skip_entity_detection: true },
+      richMessage: { markdown: richMarkdown },
     });
   };
 }