@llblab/pi-telegram 0.17.4 → 0.18.0

package/lib/preview.ts

@@ -6,6 +6,10 @@
 
 import { normalizeTelegramNativeMarkdown } from "./replies.ts";
 import { stripTelegramCommentMarkupForPreview } from "./outbound.ts";
+import {
+  getTelegramTargetThreadParams,
+  type TelegramTarget,
+} from "./target.ts";
 import { shouldSuppressPreviewForVoice } from "./voice.ts";
 
 const TELEGRAM_PREVIEW_THROTTLE_MS = 0;
@@ -29,9 +33,7 @@ export interface TelegramPreviewRuntimeState extends TelegramPreviewState {
 
 export type TelegramPreviewReplyMarkup = unknown;
 
-export interface TelegramPreviewRuntimeDeps<
-  TReplyMarkup = TelegramPreviewReplyMarkup,
-> {
+export interface TelegramPreviewRuntimeDeps {
   getState: () => TelegramPreviewRuntimeState | undefined;
   setState: (state: TelegramPreviewRuntimeState | undefined) => void;
   clearScheduledFlush: (state: TelegramPreviewRuntimeState) => void;
@@ -59,6 +61,8 @@ export interface TelegramPreviewRuntimeDeps<
 
 export interface TelegramPreviewActiveTurn {
   chatId: number;
+  replyToMessageId?: number;
+  target?: TelegramTarget;
   voiceReplyPreferred?: boolean;
   voiceReplyRequired?: boolean;
 }
@@ -77,7 +81,7 @@ export interface TelegramAssistantMessagePreviewStartDeps<
     chatId: number,
     markdown: string,
     replyToMessageId?: number,
-    options?: { replyMarkup?: TReplyMarkup },
+    options?: { replyMarkup?: TReplyMarkup; target?: TelegramTarget },
   ) => Promise<boolean>;
 }
 
@@ -88,7 +92,10 @@ export interface TelegramAssistantMessagePreviewUpdateDeps<TMessage> {
   setState: (state: TelegramPreviewRuntimeState | undefined) => void;
   createPreviewState: () => TelegramPreviewRuntimeState;
   getMessageText: (message: TMessage) => string;
-  schedulePreviewFlush: (chatId: number) => void;
+  schedulePreviewFlush: (
+    chatId: number,
+    options?: { target?: TelegramTarget },
+  ) => void;
 }
 
 export type TelegramAssistantMessagePreviewHookDeps<
@@ -110,9 +117,7 @@ export interface TelegramAssistantMessagePreviewHooks<TMessage> {
   ) => Promise<void>;
 }
 
-export interface TelegramPreviewControllerDeps<
-  TReplyMarkup = TelegramPreviewReplyMarkup,
-> {
+export interface TelegramPreviewControllerDeps {
   getDefaultReplyToMessageId?: () => number | undefined;
   maxMessageLength?: number;
   initialDraftSupport?: TelegramDraftSupport;
@@ -141,29 +146,36 @@ export interface TelegramPreviewControllerDeps<
   ) => void;
 }
 
-export interface TelegramPreviewController<
-  TReplyMarkup = TelegramPreviewReplyMarkup,
-> {
+export interface TelegramPreviewController {
   getState: () => TelegramPreviewRuntimeState | undefined;
   setState: (state: TelegramPreviewRuntimeState | undefined) => void;
   setPendingText: (text: string) => void;
   createState: () => TelegramPreviewRuntimeState;
   resetState: () => void;
-  clear: (chatId: number) => Promise<void>;
-  flush: (chatId: number) => Promise<void>;
-  scheduleFlush: (chatId: number) => void;
-  finalize: (chatId: number, replyToMessageId?: number) => Promise<boolean>;
+  clear: (
+    chatId: number,
+    options?: { target?: TelegramTarget },
+  ) => Promise<void>;
+  flush: (
+    chatId: number,
+    options?: { target?: TelegramTarget },
+  ) => Promise<void>;
+  scheduleFlush: (
+    chatId: number,
+    options?: { target?: TelegramTarget },
+  ) => void;
+  finalize: (
+    chatId: number,
+    replyToMessageId?: number,
+    options?: { target?: TelegramTarget },
+  ) => Promise<boolean>;
 }
 
-export type TelegramPreviewControllerRuntimeDeps<
-  TReplyMarkup = TelegramPreviewReplyMarkup,
-> = TelegramPreviewControllerDeps<TReplyMarkup>;
+export type TelegramPreviewControllerRuntimeDeps = TelegramPreviewControllerDeps;
 
-export function createTelegramPreviewControllerRuntime<
-  TReplyMarkup = TelegramPreviewReplyMarkup,
->(
-  deps: TelegramPreviewControllerRuntimeDeps<TReplyMarkup>,
-): TelegramPreviewController<TReplyMarkup> {
+export function createTelegramPreviewControllerRuntime(
+  deps: TelegramPreviewControllerRuntimeDeps,
+): TelegramPreviewController {
   return createTelegramPreviewController({
     getDefaultReplyToMessageId: deps.getDefaultReplyToMessageId,
     maxMessageLength: deps.maxMessageLength,
@@ -180,7 +192,7 @@ export function createTelegramPreviewControllerRuntime<
 export interface TelegramAssistantPreviewRuntimeDeps<
   TMessage,
   TReplyMarkup = TelegramPreviewReplyMarkup,
-> extends TelegramPreviewControllerRuntimeDeps<TReplyMarkup> {
+> extends TelegramPreviewControllerRuntimeDeps {
   getActiveTurn: () => TelegramPreviewActiveTurn | undefined;
   isAssistantMessage: (message: TMessage) => boolean;
   getMessageText: (message: TMessage) => string;
@@ -188,38 +200,43 @@ export interface TelegramAssistantPreviewRuntimeDeps<
     chatId: number,
     replyToMessageId: number | undefined,
     markdown: string,
-    options?: { replyMarkup?: TReplyMarkup },
+    options?: { replyMarkup?: TReplyMarkup; target?: TelegramTarget },
   ) => Promise<number | undefined>;
 }
 
 export type TelegramAssistantPreviewRuntime<
   TMessage,
   TReplyMarkup = TelegramPreviewReplyMarkup,
-> = TelegramPreviewController<TReplyMarkup> &
+> = TelegramPreviewController &
   TelegramAssistantMessagePreviewHooks<TMessage> & {
     finalizeMarkdown: (
       chatId: number,
       markdown: string,
       replyToMessageId?: number,
-      options?: { replyMarkup?: TReplyMarkup },
+      options?: { replyMarkup?: TReplyMarkup; target?: TelegramTarget },
     ) => Promise<boolean>;
   };
 
-export function createTelegramNativeMarkdownPreviewFinalizer<TReplyMarkup>(deps: {
+export function createTelegramNativeMarkdownPreviewFinalizer<
+  TReplyMarkup,
+>(deps: {
   getState: () => TelegramPreviewRuntimeState | undefined;
-  clear: (chatId: number) => Promise<void>;
+  clear: (
+    chatId: number,
+    options?: { target?: TelegramTarget },
+  ) => Promise<void>;
   discard?: () => void;
   sendMarkdownReply: (
     chatId: number,
     replyToMessageId: number | undefined,
     markdown: string,
-    options?: { replyMarkup?: TReplyMarkup },
+    options?: { replyMarkup?: TReplyMarkup; target?: TelegramTarget },
   ) => Promise<number | undefined>;
 }): (
   chatId: number,
   markdown: string,
   replyToMessageId?: number,
-  options?: { replyMarkup?: TReplyMarkup },
+  options?: { replyMarkup?: TReplyMarkup; target?: TelegramTarget },
 ) => Promise<boolean> {
   return async (chatId, markdown, replyToMessageId, options) => {
     const state = deps.getState();
@@ -262,11 +279,9 @@ export function createTelegramAssistantPreviewRuntime<
   };
 }
 
-export function createTelegramPreviewController<
-  TReplyMarkup = TelegramPreviewReplyMarkup,
->(
-  deps: TelegramPreviewControllerDeps<TReplyMarkup>,
-): TelegramPreviewController<TReplyMarkup> {
+export function createTelegramPreviewController(
+  deps: TelegramPreviewControllerDeps,
+): TelegramPreviewController {
   let state: TelegramPreviewRuntimeState | undefined;
   const clearTimer = deps.clearTimer ?? clearTimeout;
   const setTimer =
@@ -279,7 +294,7 @@ export function createTelegramPreviewController<
     deps.maxMessageLength ?? TELEGRAM_DRAFT_PREVIEW_MAX_CHARS;
   let draftSupport = deps.initialDraftSupport ?? "unknown";
   let nextDraftId = 0;
-  const getRuntimeDeps = (): TelegramPreviewRuntimeDeps<TReplyMarkup> => ({
+  const getRuntimeDeps = (): TelegramPreviewRuntimeDeps => ({
     getState: () => state,
     setState: (nextState) => {
       state = nextState;
@@ -310,25 +325,27 @@ export function createTelegramPreviewController<
     setPendingText: (text) => {
       if (state) state.pendingText = text;
     },
-    createState: () => createTelegramPreviewRuntimeState(draftSupport),
+    createState: () => createTelegramPreviewRuntimeState(),
     resetState: () => {
-      state = createTelegramPreviewRuntimeState(draftSupport);
+      state = createTelegramPreviewRuntimeState();
     },
-    clear: (chatId) => clearTelegramPreview(chatId, getRuntimeDeps()),
-    flush: (chatId) => flushTelegramPreview(chatId, getRuntimeDeps()),
-    scheduleFlush: (chatId) => {
+    clear: (chatId, options) =>
+      clearTelegramPreview(chatId, getRuntimeDeps(), options),
+    flush: (chatId, options) =>
+      flushTelegramPreview(chatId, getRuntimeDeps(), options),
+    scheduleFlush: (chatId, options) => {
       if (!state || state.flushTimer) return;
       if (throttleMs <= 0) {
-        void flushTelegramPreview(chatId, getRuntimeDeps());
+        void flushTelegramPreview(chatId, getRuntimeDeps(), options);
         return;
       }
       state.flushTimer = setTimer(() => {
-        void flushTelegramPreview(chatId, getRuntimeDeps());
+        void flushTelegramPreview(chatId, getRuntimeDeps(), options);
       }, throttleMs);
       state.flushTimer.unref?.();
     },
-    finalize: (chatId, _replyToMessageId) =>
-      finalizeTelegramPreview(chatId, getRuntimeDeps()),
+    finalize: (chatId, _replyToMessageId, options) =>
+      finalizeTelegramPreview(chatId, getRuntimeDeps(), options),
   };
 }
 
@@ -373,7 +390,14 @@ export async function handleTelegramAssistantMessagePreviewStart<
   ) {
     const previousText = state.pendingText.trim();
     if (previousText.length > 0) {
-      await deps.finalizeMarkdownPreview(turn.chatId, previousText);
+      await deps.finalizeMarkdownPreview(
+        turn.chatId,
+        previousText,
+        turn.replyToMessageId,
+        {
+          target: turn.target,
+        },
+      );
     } else {
       await deps.finalizePreview(turn.chatId);
     }
@@ -396,7 +420,7 @@ export async function handleTelegramAssistantMessagePreviewUpdate<TMessage>(
   state.pendingText = stripTelegramCommentMarkupForPreview(
     deps.getMessageText(message),
   );
-  deps.schedulePreviewFlush(turn.chatId);
+  deps.schedulePreviewFlush(turn.chatId, { target: turn.target });
 }
 
 export function buildTelegramPreviewFinalText(
@@ -407,9 +431,7 @@ export function buildTelegramPreviewFinalText(
   return state.lastSentText.trim() || undefined;
 }
 
-export function createTelegramPreviewRuntimeState(
-  draftSupport: TelegramDraftSupport,
-): TelegramPreviewRuntimeState {
+export function createTelegramPreviewRuntimeState(): TelegramPreviewRuntimeState {
   return {
     mode: "draft",
     pendingText: "",
@@ -435,12 +457,10 @@ export function shouldUseTelegramDraftPreview(_options: {
   return true;
 }
 
-export async function clearTelegramPreview<
-  TReplyMarkup = TelegramPreviewReplyMarkup,
->(
+export async function clearTelegramPreview(
   chatId: number,
-  deps: TelegramPreviewRuntimeDeps<TReplyMarkup>,
-  options: { awaitFlush?: boolean } = {},
+  deps: TelegramPreviewRuntimeDeps,
+  options: { awaitFlush?: boolean; target?: TelegramTarget } = {},
 ): Promise<void> {
   const state = deps.getState();
   if (!state) return;
@@ -453,7 +473,9 @@ export async function clearTelegramPreview<
   deps.setState(undefined);
   if (state.mode === "draft" && state.draftId !== undefined) {
     try {
-      await deps.sendDraft(chatId, state.draftId, undefined);
+      await deps.sendDraft(chatId, state.draftId, undefined, {
+        ...getTelegramTargetThreadParams(options.target ?? { chatId }),
+      });
     } catch (error) {
       deps.recordRuntimeEvent?.("preview", error, {
         phase: "clear-draft",
@@ -493,8 +515,11 @@ function createTelegramDraftInlineState(): TelegramDraftInlineState {
   };
 }
 
-function isTelegramDraftInlineStateClosed(state: TelegramDraftInlineState): boolean {
-  return state.codeTicks === 0 &&
+function isTelegramDraftInlineStateClosed(
+  state: TelegramDraftInlineState,
+): boolean {
+  return (
+    state.codeTicks === 0 &&
     !state.htmlComment &&
     !state.displayMath &&
     !state.fence &&
@@ -504,7 +529,8 @@ function isTelegramDraftInlineStateClosed(state: TelegramDraftInlineState): bool
     !state.emphasisUnderscore &&
     !state.strike &&
     !state.linkText &&
-    !state.linkDestination;
+    !state.linkDestination
+  );
 }
 
 function countRepeatedChars(text: string, index: number, char: string): number {
@@ -515,16 +541,25 @@ function countRepeatedChars(text: string, index: number, char: string): number {
 
 function isEscapedMarkdownChar(text: string, index: number): boolean {
   let slashCount = 0;
-  for (let cursor = index - 1; cursor >= 0 && text[cursor] === "\\"; cursor -= 1) {
+  for (
+    let cursor = index - 1;
+    cursor >= 0 && text[cursor] === "\\";
+    cursor -= 1
+  ) {
     slashCount += 1;
   }
   return slashCount % 2 === 1;
 }
 
-function isInlineDelimiterCandidate(text: string, index: number, length: number): boolean {
+function isInlineDelimiterCandidate(
+  text: string,
+  index: number,
+  length: number,
+): boolean {
   const previous = text[index - 1] ?? "";
   const next = text[index + length] ?? "";
-  if (!next || /\s/.test(next)) return previous.length > 0 && !/\s/.test(previous);
+  if (!next || /\s/.test(next))
+    return previous.length > 0 && !/\s/.test(previous);
   if (!previous || /\s/.test(previous)) return true;
   return /[\p{P}\p{S}]/u.test(previous) || /[\p{P}\p{S}]/u.test(next);
 }
@@ -580,12 +615,18 @@ function updateTelegramDraftInlineStateForLine(
       state.linkDestination = false;
       continue;
     }
-    if (line.startsWith("~~", index) && isInlineDelimiterCandidate(line, index, 2)) {
+    if (
+      line.startsWith("~~", index) &&
+      isInlineDelimiterCandidate(line, index, 2)
+    ) {
       state.strike = !state.strike;
       index += 1;
       continue;
     }
-    if (line.startsWith("**", index) && isInlineDelimiterCandidate(line, index, 2)) {
+    if (
+      line.startsWith("**", index) &&
+      isInlineDelimiterCandidate(line, index, 2)
+    ) {
       state.strongAsterisk = !state.strongAsterisk;
       index += 1;
       continue;
@@ -594,7 +635,10 @@ function updateTelegramDraftInlineStateForLine(
       state.emphasisAsterisk = !state.emphasisAsterisk;
       continue;
     }
-    if (line.startsWith("__", index) && isInlineDelimiterCandidate(line, index, 2)) {
+    if (
+      line.startsWith("__", index) &&
+      isInlineDelimiterCandidate(line, index, 2)
+    ) {
       state.strongUnderscore = !state.strongUnderscore;
       index += 1;
       continue;
@@ -611,7 +655,11 @@ function updateTelegramDraftBlockStateForLine(
 ): boolean {
   const fenceMatch = line.match(/^ {0,3}(`{3,}|~{3,})/);
   if (state.fence) {
-    if (new RegExp(`^ {0,3}${state.fence.marker}{${state.fence.length},}\\s*$`).test(line)) {
+    if (
+      new RegExp(
+        `^ {0,3}${state.fence.marker}{${state.fence.length},}\\s*$`,
+      ).test(line)
+    ) {
       state.fence = undefined;
     }
     return true;
@@ -622,7 +670,10 @@ function updateTelegramDraftBlockStateForLine(
   }
   if (fenceMatch) {
     const markerText = fenceMatch[1] ?? "```";
-    state.fence = { marker: markerText[0] as "`" | "~", length: markerText.length };
+    state.fence = {
+      marker: markerText[0] as "`" | "~",
+      length: markerText.length,
+    };
     return true;
   }
   if (line.trim() === "$$") {
@@ -654,9 +705,10 @@ export function getSafeTelegramRichMarkdownDraftPrefix(
 ): string | undefined {
   const source = markdown.trim();
   if (!source) return undefined;
-  const limited = source.length > maxMessageLength
-    ? source.slice(0, maxMessageLength)
-    : source;
+  const limited =
+    source.length > maxMessageLength
+      ? source.slice(0, maxMessageLength)
+      : source;
   const safeEnd = findSafeTelegramRichMarkdownDraftEnd(limited);
   if (safeEnd > 0) return limited.slice(0, safeEnd).trimEnd() || undefined;
   let candidateEnd = limited.length;
@@ -683,15 +735,17 @@ function buildTelegramNativeMarkdownPreviewSnapshot(
   return { text: safeText };
 }
 
-async function performTelegramPreviewFlush<
-  TReplyMarkup = TelegramPreviewReplyMarkup,
->(
+async function performTelegramPreviewFlush(
   chatId: number,
   state: TelegramPreviewRuntimeState,
-  deps: TelegramPreviewRuntimeDeps<TReplyMarkup>,
+  deps: TelegramPreviewRuntimeDeps,
+  options: { target?: TelegramTarget } = {},
 ): Promise<void> {
   if (deps.canSend && !deps.canSend()) {
-    await clearTelegramPreview(chatId, deps, { awaitFlush: false });
+    await clearTelegramPreview(chatId, deps, {
+      awaitFlush: false,
+      target: options.target,
+    });
     return;
   }
   const snapshot = buildTelegramNativeMarkdownPreviewSnapshot(
@@ -712,6 +766,7 @@ async function performTelegramPreviewFlush<
         chatId,
         draftId,
         normalizeTelegramNativeMarkdown(snapshot.text),
+        { ...getTelegramTargetThreadParams(options.target ?? { chatId }) },
       );
       deps.setDraftSupport("supported");
       state.mode = "draft";
@@ -728,11 +783,10 @@ async function performTelegramPreviewFlush<
   }
 }
 
-export async function flushTelegramPreview<
-  TReplyMarkup = TelegramPreviewReplyMarkup,
->(
+export async function flushTelegramPreview(
   chatId: number,
-  deps: TelegramPreviewRuntimeDeps<TReplyMarkup>,
+  deps: TelegramPreviewRuntimeDeps,
+  options: { target?: TelegramTarget } = {},
 ): Promise<void> {
   const state = deps.getState();
   if (!state) return;
@@ -746,7 +800,7 @@ export async function flushTelegramPreview<
     do {
       state.flushRequested = false;
       try {
-        await performTelegramPreviewFlush(chatId, state, deps);
+        await performTelegramPreviewFlush(chatId, state, deps, options);
       } catch (error) {
         deps.recordRuntimeEvent?.("preview", error, {
           phase: "flush",
@@ -766,22 +820,21 @@ export async function flushTelegramPreview<
   }
 }
 
-export async function finalizeTelegramPreview<
-  TReplyMarkup = TelegramPreviewReplyMarkup,
->(
+export async function finalizeTelegramPreview(
   chatId: number,
-  deps: TelegramPreviewRuntimeDeps<TReplyMarkup>,
+  deps: TelegramPreviewRuntimeDeps,
+  options: { target?: TelegramTarget } = {},
 ): Promise<boolean> {
   const state = deps.getState();
   if (!state) return false;
   if (deps.canSend && !deps.canSend()) {
-    await clearTelegramPreview(chatId, deps);
+    await clearTelegramPreview(chatId, deps, options);
     return false;
   }
-  await flushTelegramPreview(chatId, deps);
+  await flushTelegramPreview(chatId, deps, options);
   const finalText = buildTelegramPreviewFinalText(state);
   if (!finalText) {
-    await clearTelegramPreview(chatId, deps);
+    await clearTelegramPreview(chatId, deps, options);
     return false;
   }
   deps.setState(undefined);

package/lib/prompt-templates.ts

@@ -1,7 +1,7 @@
 /**
- * π prompt-template bridge helpers
+ * Pi prompt-template bridge helpers
  * Zones: pi agent prompts, telegram controls, filesystem
- * Discovers π prompt-template slash commands and expands them before Telegram queue dispatch
+ * Discovers Pi prompt-template slash commands and expands them before Telegram queue dispatch
  */
 
 import { readFileSync } from "node:fs";
@@ -129,7 +129,7 @@ export function getTelegramPromptTemplateCommands(
 export function createTelegramPromptTemplateCommandGetter(
   deps: TelegramPromptTemplateCommandGetterDeps,
 ): () => TelegramPromptTemplateCommand[] {
-  return function getPromptTemplateCommands() {
+  return () => {
     return getTelegramPromptTemplateCommands(
       deps.getCommands(),
       new Set([

package/lib/prompts.ts

@@ -4,41 +4,85 @@
  * Owns Telegram-specific system prompt suffixes injected into pi agent turns
  */
 
-import type { BeforeAgentStartEvent } from "./pi.ts";
+import { Type } from "@sinclair/typebox";
+
+import type { BeforeAgentStartEvent, ExtensionAPI } from "./pi.ts";
 import { TELEGRAM_PREFIX } from "./turns.ts";
 
 const LOCAL_SYSTEM_PROMPT_SUFFIX = `
 
-Telegram bridge extension is available.
-
-Local/TUI Telegram delivery:
-- Answer ordinary local prompts normally; do not add Telegram action comments unless the user explicitly asks for Telegram delivery.
-- For explicit Telegram file delivery, call \`telegram_attach(local_path)\`. For explicit Telegram text delivery, call \`telegram_message(...)\`.
-- Direct local/TUI Telegram delivery requires this π instance to own \`/telegram-connect\`; if ownership is elsewhere, connect/take over first instead of bypassing the lock.
-`;
+Telegram bridge available. Do not use it from local/TUI prompts unless explicitly asked.`;
 
 const TELEGRAM_TURN_SYSTEM_PROMPT_SUFFIX = `
 
-Telegram-originated turn context:
-- \`[telegram]\` marks Telegram-originated messages. Suffixes \`|from:user\` (sender) and \`|guest:group\` (guest mode — message from another chat where the bot is not a member) may be present; the bot sees the message as if forwarded from that user/chat.
-- \`[reply]\` is quoted context from the replied-to message, not a new instruction by itself. Suffix \`|from:user\` identifies the original author in guest-mode replies. Use it to resolve references like "this", "it", or "that message"; the actual instruction is before [reply] unless it explicitly asks to act on the quote.
-- \`[attachments]\` gives a base directory plus relative local files; resolve and read them as needed. \`[outputs]\` contains inbound-handler stdout such as transcriptions or extracted text for those attachments.
-- \`[time]\` gives the wall-clock time for this Telegram turn when the operator enabled time injection. Use it for relative-date requests like "today", "now", or scheduling; otherwise do not mention it.
-- \`[voice]\` describes Telegram voice reply policy for this turn. \`manual\` means answer normally and use explicit \`telegram_voice\` markup only when a spoken reply is useful; \`mirror\` means voice input prefers a voice reply; \`always\` means the final reply is expected to be converted to voice, so keep it TTS-friendly.
-- Unknown \`[callback] ...\` messages may be intended for another extension; if you see one, say the callback was not handled and the environment may be misconfigured.
-
-Telegram-visible output:
-- Telegram is mobile-first: keep answers easy to scan, use headings/lists when useful, and avoid unnecessarily huge blocks of text.
-- For formulas, use math delimiters like \`$E = mc^2$\` for inline formulas and \`$$\\nE = mc^2\\n$$\` for block formulas; do not wrap formulas in backticks unless they should render as literal code.
-- Use inline code for short copyable literals (commands, paths, IDs, symbols); avoid wide monospace blocks unless structure or literal code requires them.
-- For requested/generated files, call \`telegram_attach(local_path)\`; during Telegram turns it attaches files to the active reply, and during explicit local/TUI Telegram-delivery requests it sends files directly to the paired/default chat or an explicit \`chat_id\`. If a local/TUI user explicitly asks to send a text message to Telegram, use \`telegram_message\` with Markdown text; embed the same top-level \`telegram_button\` comments when inline prompt buttons are needed, because Telegram buttons must belong to a message. Direct local/TUI Telegram delivery requires this π instance to own \`/telegram-connect\`; if ownership is elsewhere, connect/take over first instead of bypassing the lock.
-
-Native outbound actions:
-- Use normal Rich Markdown for visible text. Use top-level column-zero hidden Markdown comments outside code, quotes, and lists only for native actions; the bridge strips them after agent_end and turns them into Telegram-native artifacts/reply_markup. Do not render button JSON, do not invent standalone button tools, and do not call/register transport/TTS/text-to-OGG tools for ordinary Telegram-turn voice/buttons.
-- \`telegram_voice\`: text is synthesized by the registered voice synthesis provider and delivered by pi-telegram. Use body text for multiline voice, \`<!-- telegram_voice text="Short summary" -->\` for explicit one-line text, or \`<!-- telegram_voice: Short summary -->\` for one-line text with no attributes. A companion summary is optional, no specific summary format is required. Keep it TTS-friendly; avoid raw Markdown, code, formulas, tables, or long lists.
-- \`telegram_button\`: callback prompt is routed back as a normal Telegram turn. Use \`<!-- telegram_button: OK -->\` when prompt equals label, \`<!-- telegram_button label=Continue prompt="Continue with the current plan." -->\` for one-line prompts, or body form \`<!-- telegram_button label="Show risks"\nList the main risks first.\n-->\` for multiline prompts. Do not put button comments inline after visible text, inside code fences, block quotes, lists, or indented examples; those are literal Markdown, not buttons.
-- If only hidden action comments would remain, add visible parent text like "Choose one:" so Telegram has a message to attach buttons to.
-`;
+Telegram turn note: If context was compacted or you need the pi-telegram bridge contract, call tool \`telegram_help\`.`;
+
+const TELEGRAM_HELP_TEXT = `--- TELEGRAM BRIDGE HELP ---
+
+How to understand Telegram turns:
+- \`[telegram|thread:name|from:user|guest:group]\` marks Telegram origin and attributes.
+- \`thread\` is the visible Thread identity in Threaded Mode; it is not a bus role.
+- \`[reply]\` is quoted context only; act on the user's current instruction.
+- \`[attachments]\` are local files; \`[outputs]\` are handler results/transcripts; \`[time]\` is wall-clock context; \`[voice]\` gives reply-mode policy.
+
+How to answer Telegram turns:
+- Reply in concise, scannable mobile Telegram Rich Markdown.
+- Use \`$...$\` for inline math and \`$$...$$\` for block math.
+- Real code blocks must stay literal.
+- For generated/requested files, call \`telegram_attach(local_path)\`; do not only mention the path.
+
+Assistant-authored Telegram actions:
+- \`telegram_voice\` and \`telegram_button\` are hidden top-level HTML comments, not Pi tools.
+- Put action comments at column zero, outside code, quotes, lists, and indented examples.
+- Voice forms: \`<!-- telegram_voice text="Short summary" -->\` or \`<!-- telegram_voice: Short summary -->\`.
+- Keep voice text TTS-friendly; avoid raw Markdown, code, and tables in voice text.
+- Voice delivery generates and attaches OGG automatically; do not also call \`telegram_attach\` for the same audio.
+- Button forms: \`<!-- telegram_button: OK -->\`, \`<!-- telegram_button label=Continue prompt="Continue with the current plan." -->\`, or multiline \`<!-- telegram_button label="Show risks"\nList the main risks first.\n-->\`.
+- If hidden comments would be the whole reply, add visible text such as \`Choose one:\`.
+
+Local/TUI direct delivery:
+- Do not send Telegram actions from local/TUI prompts unless explicitly asked.
+- Use \`telegram_attach\` for files and \`telegram_message\` for direct Markdown text.
+- Direct delivery requires this Pi instance to own \`/telegram-connect\` or be registered with the Threaded Mode bus.
+- For explicit targets, pass \`chat_id\` plus optional \`thread_id\`; registered followers default to their assigned Thread target.
+- Do not use \`telegram_message\` for ordinary Telegram-originated replies; answer normally and let the bridge deliver the active turn reply.
+
+Threaded Mode:
+- pi-telegram supports private-chat Threaded Mode when BotFather Topics/Threaded Mode are enabled.
+- Product/user language is Thread; Bot API primitive names may still say topic.
+- Threaded Mode has one leader transport and visible follower Pi processes joined manually through \`/telegram-connect\`.
+- Thread names are bridge-assigned or preserved identities; do not invent rename prompts or use a rename tool.
+- The \`All\` surface is for routing/control, not hidden Pi process creation.
+
+Configurable handlers:
+- \`telegram.json\` can add no-code \`inboundHandlers\`/\`outboundHandlers\` using command templates before writing an extension.
+- For speech-to-text, configure an \`inboundHandlers\` entry matching \`type: "voice"\` or \`mime: "audio/*"\`; stdout becomes \`[outputs]\` prompt context.
+- If command-template config is not enough, build a companion extension through the public pi-telegram APIs; do not import package-private \`lib/*\` paths.
+
+Debugging pi-telegram:
+- Inspect \`~/.pi/agent/tmp/telegram/state.json\` for runtime state, roster, bindings, slots, reservations, and diagnostics.
+- Inspect \`~/.pi/agent/tmp/telegram/logs.jsonl\` for redacted runtime event evidence.
+- Use terminal \`telegram-status\` for compact human health; use \`telegram-status --debug\` for the full human-readable diagnostic dump.`;
+
+export function getTelegramHelpText(): string {
+  return TELEGRAM_HELP_TEXT;
+}
+
+export function registerTelegramHelpTool(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "telegram_help",
+    label: "Telegram Help",
+    description:
+      "Read pi-telegram usage guidance for delivery actions, Threaded Mode, handlers, formatting, and debugging.",
+    parameters: Type.Object({}),
+    async execute() {
+      return {
+        content: [{ type: "text", text: getTelegramHelpText() }],
+        details: {},
+      };
+    },
+  });
+}
 
 export function buildTelegramBridgeSystemPrompt(options: {
   prompt: string;
@@ -48,7 +92,13 @@ export function buildTelegramBridgeSystemPrompt(options: {
   telegramTurnSystemPromptSuffix: string;
 }): { systemPrompt: string } {
   const telegramPrefix = options.telegramPrefix ?? TELEGRAM_PREFIX;
-  const telegramTurn = options.prompt.trimStart().startsWith(telegramPrefix);
+  const telegramHead = telegramPrefix.endsWith("]")
+    ? telegramPrefix.slice(0, -1)
+    : telegramPrefix;
+  const trimmedPrompt = options.prompt.trimStart();
+  const telegramTurn =
+    trimmedPrompt.startsWith(`${telegramHead}]`) ||
+    trimmedPrompt.startsWith(`${telegramHead}|`);
   const telegramSuffix = telegramTurn
     ? `${options.telegramTurnSystemPromptSuffix}\n- The current user message came from Telegram.`
     : "";
@@ -92,7 +142,7 @@ export function createTelegramProactiveBeforeAgentStartHook<TContext>(
   ctx: TContext,
 ) => Promise<{ systemPrompt: string }> {
   const baseHook = deps.baseHook ?? createTelegramBeforeAgentStartHook();
-  return async function onBeforeAgentStart(event, ctx) {
+  return async (event, ctx) => {
     if (!deps.isConfigured()) return { systemPrompt: event.systemPrompt };
     const result = baseHook(event);
     if (!deps.isProactivePushEnabled()) return result;