@llblab/pi-telegram 0.6.0 → 0.6.1

package/README.md

@@ -171,7 +171,7 @@ A TTS plus MP3-to-OGG setup can be expressed as `template: [...]`. The bridge pr
 
 #### Buttons
 
-Button blocks attach inline quick replies to the final text. Use one independent `telegram_button` block per action; its `label` is shown in Telegram and its body is sent back to pi when tapped:
+Button blocks attach inline quick replies to the final text. Use one independent `telegram_button` block per action; its `label` is shown in Telegram and its body is sent back to pi when tapped. If the prompt should equal the label, the body can be omitted:
 
 ```md
 I can continue.
@@ -179,6 +179,8 @@ I can continue.
 <!-- telegram_button label="Continue"
 Continue with the current plan.
 -->
+
+<!-- telegram_button label="OK" -->
 ```
 
 Button prompts are routed back into the normal Telegram queue as prompt turns. Outbound handler details are documented in [`docs/outbound-handlers.md`](./docs/outbound-handlers.md).

package/docs/architecture.md

@@ -155,7 +155,7 @@ Telegram prompt responses use explicit delivery context to attach outbound text,
 
 Outbound files are sent only after the active Telegram turn completes, must be staged through the `telegram_attach` tool, are staged atomically per tool call, are checked against a default 50 MiB limit configurable through `PI_TELEGRAM_OUTBOUND_ATTACHMENT_MAX_BYTES` or `TELEGRAM_MAX_ATTACHMENT_SIZE_BYTES`, and use file-backed multipart blobs so large sends do not require preloading whole files into memory.
 
-Assistant-authored outbound actions use final-message markup instead of agent tool calls. Preview updates strip closed top-level HTML comments and currently open/partial top-level comment starts before rendering, so users do not see transient metadata even when streaming flushes happen after only `<`, `<!`, or `<!--`. On `agent_end`, the bridge removes top-level comments from the Markdown text reply, but treats column-zero top-level `<!-- telegram_voice ... -->` and `<!-- telegram_button ... -->` blocks specially before delivery; comments inside fenced code, quotes, lists, or indented examples stay literal. Voice maps to the first matching `outboundHandlers[]` entry with `type: "voice"`, synthesizes the block body through command-template execution, and uploads the generated OGG/Opus file via Telegram `sendVoice`; when no outbound voice handler is configured, it silently skips voice delivery. The `template: [...]` form can express TTS plus MP3-to-OGG conversion using configured templates and bridge-provided `{text}`, `{mp3}`, and `{ogg}` placeholders. Top-level `args` and `defaults` apply to all composed steps unless a step defines private values, top-level `timeout` wraps the whole sequence, and each step receives the previous step's stdout on stdin by default, without hard-coded filesystem defaults. Button blocks are built in: each `telegram_button` block becomes one inline-keyboard button on the final text, and callback clicks enqueue the configured prompt text as a normal Telegram prompt turn. This keeps technical Markdown, code, tables, formulas, and numbered lists in the text channel when appropriate while allowing TTS-friendly voice messages and tappable continuations without invoking `telegram_attach` or extra transport tools.
+Assistant-authored outbound actions use final-message markup instead of agent tool calls. Preview updates strip closed top-level HTML comments and currently open/partial top-level comment starts before rendering, so users do not see transient metadata even when streaming flushes happen after only `<`, `<!`, or `<!--`. On `agent_end`, the bridge removes top-level comments from the Markdown text reply, but treats column-zero top-level `<!-- telegram_voice ... -->` and `<!-- telegram_button ... -->` blocks specially before delivery; comments inside fenced code, quotes, lists, or indented examples stay literal, including fenced blocks with Markdown-valid indented closing fences. Voice maps to the first matching `outboundHandlers[]` entry with `type: "voice"`, synthesizes the block body through command-template execution, and uploads the generated OGG/Opus file via Telegram `sendVoice`; when no outbound voice handler is configured, it silently skips voice delivery. The `template: [...]` form can express TTS plus MP3-to-OGG conversion using configured templates and bridge-provided `{text}`, `{mp3}`, and `{ogg}` placeholders. Top-level `args` and `defaults` apply to all composed steps unless a step defines private values, top-level `timeout` wraps the whole sequence, and each step receives the previous step's stdout on stdin by default, without hard-coded filesystem defaults. Button blocks are built in: each `telegram_button` block becomes one inline-keyboard button on the final text, and callback clicks enqueue the configured prompt text, or the button label when the body is omitted, as a normal Telegram prompt turn. This keeps technical Markdown, code, tables, formulas, and numbered lists in the text channel when appropriate while allowing TTS-friendly voice messages and tappable continuations without invoking `telegram_attach` or extra transport tools.
 
 ## Interactive Controls
 

package/docs/attachment-handlers.md

@@ -39,7 +39,7 @@ Attachment handlers support these built-in placeholders:
 
 `defaults` may provide additional placeholder values such as `{lang}` or `{model}`. `args` is only a string-array declaration of supported placeholders; defaults belong in `defaults` or inline placeholders such as `{lang=ru}`. Examples prefer explicit flag-style CLIs for readability, but positional forms such as `/path/to/stt {file} {lang=ru} {model=voxtral-mini-latest}` are equally valid when the target script supports them.
 
-If a top-level one-step handler template has no `{file}` placeholder, the downloaded file path is appended as the last command arg for backwards compatibility. Composition steps are plain command templates and do not receive implicit file-path args; include `{file}` explicitly where needed.
+If a top-level one-step handler template has no `{file}` placeholder, the downloaded file path is appended as the last command arg as a one-step handler convenience. Composition steps are plain command templates and do not receive implicit file-path args; include `{file}` explicitly where needed.
 
 ## Ordered Fallbacks
 

package/docs/outbound-handlers.md

@@ -75,7 +75,7 @@ For one-step `template` handlers, stdout remains the default result channel: the
 
 ## Buttons Markup
 
-Assistant replies can include independent button blocks. The block body is the prompt sent back to pi when the user taps the button:
+Assistant replies can include independent button blocks. The block body is the prompt sent back to pi when the user taps the button; omit the body when the prompt should equal the label:
 
 ```md
 I can continue.
@@ -87,11 +87,13 @@ Continue with the current plan.
 <!-- telegram_button label="Show risks"
 List the main risks first.
 -->
+
+<!-- telegram_button label="Done" -->
 ```
 
 Rules:
 
-- `telegram_button label="Label"` creates one independent button row whose prompt is the block body.
+- `telegram_button label="Label"` creates one independent button row whose prompt is the block body, or the label itself when the body is omitted.
 - The opening `<!-- telegram_button` marker must start at column zero on a top-level line outside fenced code, quotes, and lists; otherwise it is rendered as literal Markdown.
 - Use one block per button; this mirrors HTML's singular element model and avoids a nested button DSL inside comments.
 - Button actions are stored in memory with short `callback_data`; Telegram never sees the full prompt in the button payload.

package/lib/command-templates.ts

@@ -33,6 +33,7 @@ export interface CommandTemplateExecOptions {
   timeout?: number;
   signal?: AbortSignal;
   stdin?: string;
+  killGrace?: number;
 }
 
 export interface CommandTemplateExecResult {
@@ -207,18 +208,20 @@ export function execCommandTemplate(
     let killed = false;
     let settled = false;
     let timeoutId: NodeJS.Timeout | undefined;
+    let killTimeoutId: NodeJS.Timeout | undefined;
     const killProcess = (): void => {
       if (killed) return;
       killed = true;
       proc.kill("SIGTERM");
-      setTimeout(() => {
-        if (!proc.killed) proc.kill("SIGKILL");
-      }, 5000);
+      killTimeoutId = setTimeout(() => {
+        if (!settled) proc.kill("SIGKILL");
+      }, options.killGrace ?? 5000);
     };
     const settle = (code: number): void => {
       if (settled) return;
       settled = true;
       if (timeoutId) clearTimeout(timeoutId);
+      if (killTimeoutId) clearTimeout(killTimeoutId);
       if (options.signal)
         options.signal.removeEventListener("abort", killProcess);
       resolve({ stdout, stderr, code, killed });

package/lib/outbound-handlers.ts

@@ -101,6 +101,11 @@ interface TelegramTopLevelHtmlComment {
   end: number;
 }
 
+interface TelegramTopLevelFenceState {
+  marker: "`" | "~";
+  length: number;
+}
+
 function getMarkdownLineEnd(markdown: string, offset: number): number {
   const newlineIndex = markdown.indexOf("\n", offset);
   return newlineIndex === -1 ? markdown.length : newlineIndex + 1;
@@ -114,9 +119,29 @@ function getMarkdownLineText(
   return markdown.slice(offset, end).replace(/\r?\n$/, "");
 }
 
-function getTopLevelFenceMarker(line: string): "```" | "~~~" | undefined {
-  const match = line.match(/^(?: {0,3})(```|~~~)/);
-  return match?.[1] as "```" | "~~~" | undefined;
+function getTopLevelOpeningFence(
+  line: string,
+): TelegramTopLevelFenceState | undefined {
+  const match = line.match(/^(?: {0,3})(`{3,}|~{3,})/);
+  const sequence = match?.[1];
+  if (!sequence) return undefined;
+  return {
+    marker: sequence[0] as "`" | "~",
+    length: sequence.length,
+  };
+}
+
+function isTopLevelClosingFence(
+  line: string,
+  fence: TelegramTopLevelFenceState,
+): boolean {
+  const match = line.match(/^(?: {0,3})(`{3,}|~{3,})([ \t]*)$/);
+  const sequence = match?.[1];
+  return (
+    !!sequence &&
+    sequence[0] === fence.marker &&
+    sequence.length >= fence.length
+  );
 }
 
 function collectTopLevelHtmlComments(markdown: string): {
@@ -125,18 +150,18 @@ function collectTopLevelHtmlComments(markdown: string): {
 } {
   const comments: TelegramTopLevelHtmlComment[] = [];
   let offset = 0;
-  let fenceMarker: "```" | "~~~" | undefined;
+  let fence: TelegramTopLevelFenceState | undefined;
   while (offset < markdown.length) {
     const lineEnd = getMarkdownLineEnd(markdown, offset);
     const line = getMarkdownLineText(markdown, offset, lineEnd);
-    if (fenceMarker) {
-      if (line.startsWith(fenceMarker)) fenceMarker = undefined;
+    if (fence) {
+      if (isTopLevelClosingFence(line, fence)) fence = undefined;
       offset = lineEnd;
       continue;
     }
-    const nextFenceMarker = getTopLevelFenceMarker(line);
-    if (nextFenceMarker) {
-      fenceMarker = nextFenceMarker;
+    const nextFence = getTopLevelOpeningFence(line);
+    if (nextFence) {
+      fence = nextFence;
       offset = lineEnd;
       continue;
     }
@@ -174,19 +199,19 @@ function findTopLevelOpenOrPartialHtmlCommentIndex(markdown: string): number {
   const { openCommentStart } = collectTopLevelHtmlComments(markdown);
   if (openCommentStart !== undefined) return openCommentStart;
   let offset = 0;
-  let fenceMarker: "```" | "~~~" | undefined;
+  let fence: TelegramTopLevelFenceState | undefined;
   while (offset < markdown.length) {
     const lineEnd = getMarkdownLineEnd(markdown, offset);
     const line = getMarkdownLineText(markdown, offset, lineEnd);
     const isLastLine = lineEnd >= markdown.length;
-    if (fenceMarker) {
-      if (line.startsWith(fenceMarker)) fenceMarker = undefined;
+    if (fence) {
+      if (isTopLevelClosingFence(line, fence)) fence = undefined;
       offset = lineEnd;
       continue;
     }
-    const nextFenceMarker = getTopLevelFenceMarker(line);
-    if (nextFenceMarker) {
-      fenceMarker = nextFenceMarker;
+    const nextFence = getTopLevelOpeningFence(line);
+    if (nextFence) {
+      fence = nextFence;
       offset = lineEnd;
       continue;
     }
@@ -251,9 +276,8 @@ function normalizeMarkdownAfterVoiceExtraction(markdown: string): string {
 
 export function stripTelegramCommentMarkupForPreview(markdown: string): string {
   const withoutClosedBlocks = replaceTopLevelHtmlComments(markdown, () => "");
-  const openBlockIndex = findTopLevelOpenOrPartialHtmlCommentIndex(
-    withoutClosedBlocks,
-  );
+  const openBlockIndex =
+    findTopLevelOpenOrPartialHtmlCommentIndex(withoutClosedBlocks);
   const previewMarkdown =
     openBlockIndex >= 0
       ? withoutClosedBlocks.slice(0, openBlockIndex)
@@ -265,9 +289,8 @@ export function stripTelegramCommentMarkupForDelivery(
   markdown: string,
 ): string {
   const withoutClosedBlocks = replaceTopLevelHtmlComments(markdown, () => "");
-  const openBlockIndex = findTopLevelOpenOrPartialHtmlCommentIndex(
-    withoutClosedBlocks,
-  );
+  const openBlockIndex =
+    findTopLevelOpenOrPartialHtmlCommentIndex(withoutClosedBlocks);
   const deliveryMarkdown =
     openBlockIndex >= 0
       ? withoutClosedBlocks.slice(0, openBlockIndex)
@@ -343,7 +366,9 @@ function getVoiceReplyCompositionStepTimeout(
 ): number {
   const remaining = getRemainingVoiceReplyTimeout(handlerTimeout, startedAt);
   const stepTimeout = getVoiceReplyConfiguredTimeout(step);
-  return stepTimeout === undefined ? remaining : Math.min(stepTimeout, remaining);
+  return stepTimeout === undefined
+    ? remaining
+    : Math.min(stepTimeout, remaining);
 }
 
 function formatVoiceReplyExecutionFailure(
@@ -704,8 +729,8 @@ function parseButtonsCommentRows(
   body: string | undefined,
 ): TelegramOutboundButtonAction[][] {
   const attributes = parseButtonsCommentAttributes(head);
-  const prompt = body?.trim();
-  if (!attributes.label || !prompt) return [];
+  if (!attributes.label) return [];
+  const prompt = body?.trim() || attributes.label;
   return [[{ text: attributes.label, prompt }]];
 }
 

package/lib/prompts.ts

@@ -17,7 +17,7 @@ Telegram bridge extension is active.
 - Do not assume mentioning a local file path in plain text will send it to Telegram. Use telegram_attach.
 - For Telegram-native outbound actions, use hidden top-level Markdown comments instead of agent-side tool calls: write a normal answer plus correctly formatted column-zero \`telegram_voice\` or \`telegram_button\` blocks outside code, quotes, and lists. The bridge handles delivery after \`agent_end\`, so do not call or register transport/TTS/text-to-OGG tools for these actions.
 - A \`telegram_voice\` block body is the text to synthesize through the extension's configured outbound-handler pipeline. It may be a short companion summary when useful, but no specific summary format is required. Keep it TTS-friendly; avoid raw Markdown, code, formulas, tables, or long lists.
-- Button blocks should contain quick reply prompts the user can tap; use independent blocks like \`<!-- telegram_button label="OK"\nPrompt text\n-->\`. The callback prompt is routed back as a normal Telegram turn.`;
+- Button blocks should contain quick reply prompts the user can tap; use independent blocks like \`<!-- telegram_button label="OK"\nPrompt text\n-->\`, or \`<!-- telegram_button label="OK" -->\` when the prompt should equal the label. The callback prompt is routed back as a normal Telegram turn.`;
 
 export function buildTelegramBridgeSystemPrompt(options: {
   prompt: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "private": false,
   "description": "Better Telegram DM bridge extension for pi",
   "type": "module",