@llblab/pi-kit 0.36.3 → 0.37.1

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

@@ -34,7 +34,7 @@ export const TELEGRAM_MESSAGE_PROMPT_GUIDELINES = [
   "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 an explicitly requested channel media post, pass one local .jpg/.jpeg/.png/.webp photo or .mp4 video as media; the text becomes its caption (max 1024 characters), and albums or other media types are rejected.",
   "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.",
+  "Add buttons by embedding the same 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.",
 ] as const;
 

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

@@ -360,7 +360,7 @@ export interface TelegramTypingLoopStarterDeps<
   getDefaultChatId: () => number | undefined;
   sendTypingAction: (
     chatId: number,
-    options?: { message_thread_id?: number; assertAuthority?: () => void },
+    options?: { message_thread_id?: number; assertAuthority?: () => void; isCancelled?: () => boolean },
   ) => Promise<unknown>;
   updateStatus: (ctx: TContext, error?: string) => void;
   isContextActive?: (ctx: TContext) => boolean;
@@ -454,6 +454,7 @@ export function createTelegramTypingLoopStarter<TContext>(
         try {
           await deps.sendTypingAction(targetChatId, {
             ...actionOptions,
+            isCancelled: () => !active,
             // This stays process-local; adapters recheck it before HTTP/IPC issuance, not just loop ticks.
             assertAuthority() {
               if (!active || !canContinue()) throw new Error("Typing context authority changed.");

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

@@ -407,8 +407,8 @@ export interface TelegramApiCallOptions {
 
 export class TelegramApiAuthorityError extends Error {
   readonly requestIssued: boolean;
-  constructor(requestIssued: boolean) {
-    super("Telegram API call authority is unavailable.");
+  constructor(requestIssued: boolean, options?: ErrorOptions) {
+    super("Telegram API call authority is unavailable.", options);
     this.name = "TelegramApiAuthorityError";
     this.requestIssued = requestIssued;
   }
@@ -418,11 +418,12 @@ export class TelegramApiAuthorityError extends Error {
 export function assertTelegramApiCallAuthority(
   assertAuthority: (() => void) | undefined,
   requestIssued: boolean,
+  errorOptions?: ErrorOptions,
 ): void {
   try {
     assertAuthority?.();
   } catch {
-    throw new TelegramApiAuthorityError(requestIssued);
+    throw new TelegramApiAuthorityError(requestIssued, errorOptions);
   }
 }
 
@@ -847,6 +848,8 @@ export interface TelegramBridgeApiRuntimeDeps {
 /** Typing issuance guard is local authority, never Bot API body or IPC data. */
 export interface TelegramTypingActionOptions extends Pick<TelegramApiCallOptions, "assertAuthority"> {
   message_thread_id?: number;
+  /** Diagnostic observation only: an ended loop does not grant issuance, success or retry. */
+  isCancelled?: () => boolean;
 }
 
 export interface TelegramBridgeApiRuntime extends Pick<
@@ -1649,7 +1652,7 @@ async function callTelegramWithRetry<TResponse>(
     } catch (error) {
       // Authority refusal is never a transport failure, retry grant or acknowledged success.
       if (error instanceof TelegramApiAuthorityError) throw error;
-      assertTelegramApiCallAuthority(assertAuthority, requestIssued);
+      assertTelegramApiCallAuthority(assertAuthority, requestIssued, { cause: error });
       const retryable =
         isRetryableTelegramApiError(error) &&
         !(
@@ -2090,7 +2093,8 @@ export function createTelegramBridgeApiRuntime(
     notBeforeMs: number;
   };
   const chatActionGates = new Map<string, ChatActionGate>();
-  const chatActionChatGates = new Map<string, ChatActionGate>();
+  // Pin shared cooldowns until every concurrent Thread settles; this state never owns their sends.
+  const chatActionChatGates = new Map<string, { pendingRequests: number; notBeforeMs: number }>();
   const getChatActionKeys = (
     method: string,
     body: Record<string, unknown>,
@@ -2130,7 +2134,7 @@ export function createTelegramBridgeApiRuntime(
         }
       }
       for (const [key, candidate] of chatActionChatGates) {
-        if (!candidate.inFlight && nowMs >= candidate.notBeforeMs) {
+        if (candidate.pendingRequests === 0 && nowMs >= candidate.notBeforeMs) {
           chatActionChatGates.delete(key);
         }
       }
@@ -2146,11 +2150,10 @@ export function createTelegramBridgeApiRuntime(
         if (chatActionChatGates.size >= chatActionMaxGates) {
           return true as TResponse;
         }
-        chatGate = { notBeforeMs: 0 };
+        chatGate = { pendingRequests: 0, notBeforeMs: 0 };
         chatActionChatGates.set(chatActionKeys.chat, chatGate);
       }
       if (gate.inFlight) return (await gate.inFlight) as TResponse;
-      if (chatGate.inFlight) return true as TResponse;
       if (nowMs < gate.notBeforeMs || nowMs < chatGate.notBeforeMs) {
         return true as TResponse;
       }
@@ -2189,19 +2192,22 @@ export function createTelegramBridgeApiRuntime(
             );
             return true as TResponse;
           }
-          deps.recordRuntimeEvent(
-            "api",
-            error,
-            withTelegramTransportDiagnostics(error, { method }),
-          );
+          const diagnosticError = error instanceof TelegramApiAuthorityError && Object.hasOwn(error, "cause")
+            ? error.cause : error;
+          if (!options?.isExpectedError?.(error))
+            deps.recordRuntimeEvent(
+              "api",
+              diagnosticError,
+              withTelegramTransportDiagnostics(diagnosticError, { method }),
+            );
           throw error;
         })
         .finally(() => {
           if (gate.inFlight === request) gate.inFlight = undefined;
-          if (chatGate.inFlight === request) chatGate.inFlight = undefined;
+          chatGate.pendingRequests--;
         });
       gate.inFlight = request;
-      chatGate.inFlight = request;
+      chatGate.pendingRequests++;
       return request;
     }
     try {
@@ -2311,14 +2317,21 @@ export function createTelegramBridgeApiRuntime(
           : {}),
       }),
     sendTypingAction: createTelegramChatActionSender(
-      (chatId, action, options) =>
-        callRecorded<boolean>("sendChatAction", {
+      (chatId, action, options) => {
+        const isCancelled = options?.isCancelled;
+        return callRecorded<boolean>("sendChatAction", {
           chat_id: chatId,
           action,
           ...(options?.message_thread_id !== undefined
             ? { message_thread_id: options.message_thread_id }
             : {}),
-        }, { assertAuthority: options?.assertAuthority }),
+        }, {
+          assertAuthority: options?.assertAuthority,
+          ...(isCancelled ? {
+            isExpectedError: (error: unknown) => error instanceof TelegramApiAuthorityError && !Object.hasOwn(error, "cause") && isCancelled() === true,
+          } : {}),
+        });
+      },
       "typing",
     ),
     sendRecordVoiceAction: createTelegramChatActionSender(

package/node_modules/@llblab/pi-telegram/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-telegram",
-  "version": "0.57.11",
+  "version": "0.58.3",
   "private": false,
   "publishConfig": {
     "access": "public"

package/node_modules/@llblab/pi-telegram/skills/telegram-bridge/SKILL.md

@@ -16,12 +16,12 @@ Use Telegram as a mobile companion to the current Pi session. Preserve the exact
 | Explicitly send from local/TUI to Telegram | `telegram_message` or `telegram_attach` |
 | Explicitly send to a different live Thread | `telegram_message(thread=...)` |
 | Add buttons | Hidden comment for footer; `telegram_button` fence for in-body rows |
-| Add explicit voice | Top-level hidden action comment |
+| Add explicit voice | Hidden action comment |
 | Build a repeated deterministic interaction | Follow `generative-apps` |
 
 A connected Telegram session proves capability, not user intent. Use Telegram features on Telegram-originated turns or explicit Telegram delivery requests only. Never call `telegram_message` for the current active target.
 
-For direct delivery, Thread routing, configuration, or diagnosis, read only the applicable reference listed under [Conditional References](#conditional-references).
+For delivery, Thread routing, configuration or diagnosis, read the applicable reference under [Conditional References](#conditional-references).
 
 ## Turn Context
 
@@ -40,7 +40,7 @@ Reply in concise, phone-width Telegram Rich Markdown. Use `$...$` and `$$...$$`
 
 ## Assistant Actions
 
-`telegram_button` and `telegram_voice` are markup, not tools. Emit action comments at column zero outside lists, quotes, code, and indentation. Comments create footer buttons or voice artifacts. For buttons between paragraphs, use a column-zero triple-backtick `telegram_button` block. Both button wrappers accept the same singleton JSON/CML cell or mixed matrix; the wrapper determines placement. Telegram removes every assistant-authored HTML comment from previews and final replies regardless of owner or Markdown position; only recognized top-level wrappers activate actions; comment-only output sends no text message.
+`telegram_button` and `telegram_voice` are markup, not tools. Complete comments activate regardless of surrounding Markdown. Escape `<!--` as `&lt;!--` for literal examples; backticks and backslashes do not disable actions. Comments create footer buttons or voice artifacts. In-body fences: ≥3 backticks/tildes, optional indentation/whitespace, exact `telegram_button`; separate same-marker closure, no shorter. Both wrappers accept a singleton JSON/CML cell or mixed matrix; the wrapper determines placement. Telegram removes every assistant-authored HTML comment from previews and final replies regardless of owner or Markdown position; only complete recognized comments or valid button fences activate actions; comment-only output sends no text message.
 
 ### Shared Encoding Rule
 
@@ -61,7 +61,7 @@ Every enabled button has a self-contained prompt and an optional selection style
 - `{label|prompt|selected_style}` and `{|prompt|selected_style}` accept `primary`, `success`, or `danger`.
 - Fourth-position `1`/`true` disables, `0`/`false` enables; omission means enabled. JSON uses boolean `disabled`. `{|Next||1}` omits label/style; `{Next|||1}` omits prompt/style; `{|||1}` is blank (Telegram receives a non-breaking space). Prefer meaningful labels and retain a useful enabled action. Enabled CML requires a prompt. Disabled controls stay visible but have no callback, queued prompt, or bound-method invocation.
 - Both wrappers concatenate rows from adjacent JSON/CML cells or matrices, with optional commas. Cells are vertical; horizontal peers require a nested row: `[[{A|a}{B|b}]]`.
-- Prefer one matrix per related group. Fenced blocks stay in place in Rich mode; HTML compatibility moves them to the footer. Native rows allow eight buttons. Malformed/oversized/unclosed blocks activate nothing; drafts hide them. Outer code fences and quoted/indented examples remain literal.
+- Prefer one matrix per related group. Fenced blocks stay in place in Rich mode; HTML compatibility moves them to the footer. Native rows allow eight buttons. Malformed/oversized/unclosed blocks activate nothing; drafts hide them. Enclosing code fences and quoted/list-prefixed button fences remain literal.
 - Both placements share prompt/app routing. In-body clicks acknowledge without recoloring; selected-style highlighting remains footer-only.
 
 A single in-body button (the four-backtick wrapper below makes this a literal example):
@@ -124,6 +124,6 @@ Before replying:
 
 - Use the ordinary path for the current target and direct tools only for explicit other delivery.
 - Attach requested files rather than only mentioning them.
-- Keep action comments and button fences top-level, complete, and canonical: CML first, JSON when necessary; either syntax may coexist within one matrix.
+- Keep comments complete and button fences top-level and canonical: CML first, JSON when necessary; either syntax may coexist within one matrix.
 - Give every enabled button a self-contained prompt; preserve confirmation for dangerous actions.
 - Expose no secret or hidden reasoning.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-kit",
-  "version": "0.36.3",
+  "version": "0.37.1",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -50,7 +50,7 @@
     "@llblab/pi-codex-usage": "0.13.2",
     "@llblab/pi-grow-loop": "0.9.0",
     "@llblab/pi-state-flow": "0.26.5",
-    "@llblab/pi-telegram": "0.57.11",
+    "@llblab/pi-telegram": "0.58.3",
     "@llblab/skills": "1.15.0"
   },
   "bundledDependencies": [