@llblab/pi-telegram 0.33.0 → 0.33.2

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
+## 0.33.2: Structured Filesystem Surfaces
+
+- `Filesystem Ordering`: Sorts generated directory surfaces by visible directories, hidden directories, visible files, then hidden files, with alphabetical ordering inside each category before fixed ten-entry pagination.
+- `Surface Metadata`: Reuses compact status-style key-value rows for filesystem path and range metadata, with bold labels and inline-code values instead of middle-dot section separators or duplicated entry listings.
+
+## 0.33.1: Rendered Command Replies And Visible Compaction
+
+- `Command Rendering`: Restored the `/next` empty-queue emphasis by preserving its HTML source and forwarding `parseMode: "HTML"` through the command reply adapter, so command helpers select the renderer explicitly instead of leaking HTML or Markdown syntax as plain text.
+- `Compaction Visibility`: Reports `compacting` ahead of generic active or pending status and sends the same start/completion notices for observed automatic compaction as for manually requested compaction, while retaining queue blocking and deferred dispatch.
+
 ## 0.33.0: Matrix Controls And Pinned Filesystem Navigation
 
 - `Button Matrix`: Extended `telegram_button` and its plural alias from flat arrays to JSON matrices: top-level objects remain full-width rows, while nested arrays intentionally group one to three peer controls horizontally; empty, oversized, or deeper rows fail closed without changing existing object, attribute, or flat-array behavior.

package/docs/architecture.md

@@ -352,7 +352,7 @@ The bridge does not mirror arbitrary `ctx.ui.confirm/input/select/custom` prompt
 
 ## Diagnostics And Operational Behavior
 
-Status rendering distinguishes connected, active, dispatching, queued, tool-running, model-switching, and compacting states. If a queue mutation removes the last waiting item while Telegram-owned work still has running tools, status remains active instead of degrading to connected.
+Status rendering distinguishes connected, active, dispatching, queued, tool-running, model-switching, and compacting states; the Telegram status menu gives compaction precedence over generic active or pending work. Observed automatic compaction sends the same start and completion notices as the manual command without duplicating notices for command-owned compaction. If a queue mutation removes the last waiting item while Telegram-owned work still has running tools, status remains active instead of degrading to connected.
 
 Queue reactions are reversible shortcut controls for waiting turns. The runtime reconciles each complete `MessageReactionUpdated.new_reaction` set: any removal reaction (`👎`, `👻`, `💔`, `💩`, `🗑`) suppresses the governed prompt without discarding its queue authority; otherwise any promotion reaction (`👍`, `⚡️`, `❤️`, `🕊`, `🔥`) moves it to priority; otherwise it returns to the default lane. Suppressed prompts remain visible in the queue menu, survive authenticated queue handoff, and do not block unrelated dispatch. Reaction changes first flush a matching delayed text or media group so the governed turn exists before mutation. Once Pi has consumed a prompt, reactions cannot retract it.
 
@@ -362,7 +362,7 @@ Complete intermediate assistant text blocks from Telegram-originated activity ar
 
 `assistant.activity` is an independent bridge-owned projection over normalized Activity events. Each process reloads the shared file-backed setting at `agent-start` before activity admission, so multi-instance mode cannot continue projecting a stale broader process-local selection. Omitted values resolve to `verbose`, while invalid values fail closed to `quiet`; `thinking` and `tools` select one technical class, while `verbose` enables both. Provider-exposed thinking uses persistent ordinary HTML containing only a standard expandable blockquote with a bounded redacted latest-text window and inline Markdown rendered as Telegram HTML. Completed executed tools use native Rich Messages: each closed `<Tool>: <status>` root details node renders snake-case names as title words while preserving an uppercase two- or three-letter repeated prefix per word, then the native disclosure chevron reveals an open-by-default `arguments` child plus closed retained `update N` and `result`/`error` child details with lowercase monospaced, marker-free summaries and JSON pre blocks; known-safe Rich rejections fall back to the previous HTML disclosure. The projection captures the exact target and transport stamp at activity admission, serializes updates, preserves tool-start order, closes coalescing across assistant/thinking boundaries, bounds retained text/update memory plus edit frames and message/tool size, disables previews and HTTP(S) auto-link recognition inside technical evidence, and never replays a possibly committed send. Session generations own independent queues, so replacement drops queued old work without waiting on an old call. Both proactive prose and active-turn final delivery wait for the admitted activity queue inside their extension-owned delivery tasks, preserving technical-before-semantic ordering without delaying Pi lifecycle completion. Settlement, replacement, disconnect, failure, or stale authority clears only local ownership; already-sent activity messages remain in chat.
 
-Telegram prompt guidance is context- and authority-aware. The package and source-checkout extension both contribute `telegram-bridge` plus the optional `generated-control-surface` Skill through Pi resource discovery. The latter treats `interface = f(state, capabilities, intent)` as a renderer-neutral primitive, compiling transient evidence-backed controls over domain-owned workflows, systems, navigation, supervision, and decisions without creating parallel application state. Its filesystem adapter reserves the first full-width row for parent traversal outside root, places available Previous/Next controls together in one compact row immediately afterward, paginates directory entries in fixed pages of ten as full-width rows, emits the complete Telegram control set through one JSON-matrix action, suppresses duplicate plain/monospaced listings and default Refresh unless user preference overrides presentation, and retains an ordinary numbered fallback when buttons are unavailable. Only an exact direct owner or live registered follower exposes the two pi-telegram delivery tools, their active-tool metadata, and the compact routing suffix. Disconnect or authority loss removes those tool surfaces for subsequent requests without touching foreign tools; reconnect/recovery restores only the pi-telegram subset that was active before suspension, including across same-process reload. Telegram-originated turns route to the stable Skill contract and retain dynamic blocks such as `[voice] delivery: automatic voice`; the Skill and public documentation own syntax, target routing, Threaded Mode behavior, and diagnostics.
+Telegram prompt guidance is context- and authority-aware. The package and source-checkout extension both contribute `telegram-bridge` plus the optional `generated-control-surface` Skill through Pi resource discovery. The latter treats `interface = f(state, capabilities, intent)` as a renderer-neutral primitive, compiling transient evidence-backed controls over domain-owned workflows, systems, navigation, supervision, and decisions without creating parallel application state. Its filesystem adapter reserves the first full-width row for parent traversal outside root, places available Previous/Next controls together in one compact row immediately afterward, orders visible directories, hidden directories, visible files, and hidden files alphabetically within each category before fixed ten-entry pagination, renders path/range metadata as stacked status-style key-value rows instead of middle-dot prose, emits the complete Telegram control set through one JSON-matrix action, suppresses duplicate plain/monospaced listings and default Refresh unless user preference overrides presentation, and retains an ordinary numbered fallback when buttons are unavailable. Only an exact direct owner or live registered follower exposes the two pi-telegram delivery tools, their active-tool metadata, and the compact routing suffix. Disconnect or authority loss removes those tool surfaces for subsequent requests without touching foreign tools; reconnect/recovery restores only the pi-telegram subset that was active before suspension, including across same-process reload. Telegram-originated turns route to the stable Skill contract and retain dynamic blocks such as `[voice] delivery: automatic voice`; the Skill and public documentation own syntax, target routing, Threaded Mode behavior, and diagnostics.
 
 ## In-Flight Model Switching
 

package/lib/bindings.ts

@@ -860,6 +860,21 @@ export function registerTelegramLifecycleRuntimeHooks({
       target: turn?.target,
     });
   };
+  let observedAutomaticCompaction = false;
+  const sendCompactionNotice = async (text: string): Promise<void> => {
+    const turn = activeTurnRuntime.get();
+    const target = turn?.target ?? proactivePushTargetGetter?.();
+    if (!target) return;
+    try {
+      await sendMarkdownReply(target.chatId, turn?.replyToMessageId, text, {
+        target,
+      });
+    } catch (error) {
+      recordRuntimeEvent("delivery", error, {
+        phase: "compaction-notice",
+      });
+    }
+  };
   const compactionObserver = Lifecycle.createTelegramCompactionObserverRuntime({
     isContextActive: isSessionContextActive,
     setCompactionInProgress: lifecycle.setCompactionInProgress,
@@ -870,7 +885,10 @@ export function registerTelegramLifecycleRuntimeHooks({
       deferredQueueDispatchRuntime.request,
     dispatchNextQueuedTelegramTurn,
     recordRuntimeEvent,
-    onCompactionAbandoned: activityRuntime.onCompactionAbandoned,
+    onCompactionAbandoned: () => {
+      observedAutomaticCompaction = false;
+      activityRuntime.onCompactionAbandoned();
+    },
   });
   const messageActivityTypingHooks =
     Lifecycle.createTelegramMessageActivityTypingHooks({
@@ -902,6 +920,7 @@ export function registerTelegramLifecycleRuntimeHooks({
       activityRuntime.onSessionShutdown();
       activityVerbosityRuntime?.reset();
       assistantOutputRuntime.stop();
+      observedAutomaticCompaction = false;
       compactionObserver.onSessionShutdown();
       if (event.reason === "quit" && disconnectOnQuit) {
         try {
@@ -916,15 +935,24 @@ export function registerTelegramLifecycleRuntimeHooks({
       }
       await sessionLifecycleRuntime.onSessionShutdown(event, ctx);
     },
-    onSessionBeforeCompact(event, ctx) {
+    async onSessionBeforeCompact(event, ctx) {
       if (!isSessionContextActive(ctx)) return;
+      const shouldNotify = !(lifecycle.isCompactionInProgress?.() ?? false);
+      if (shouldNotify) observedAutomaticCompaction = true;
       activityRuntime.onCompactionStart(Pi.getSessionCompactionReason(event));
       compactionObserver.onSessionBeforeCompact(event, ctx);
+      if (shouldNotify) {
+        await sendCompactionNotice(Commands.TELEGRAM_COMPACTION_STARTED_TEXT);
+      }
     },
-    onSessionCompact(event, ctx) {
+    async onSessionCompact(event, ctx) {
       if (!isSessionContextActive(ctx)) return;
       activityRuntime.onCompactionEnd(Pi.getSessionCompactionReason(event));
       compactionObserver.onSessionCompact(event, ctx);
+      if (observedAutomaticCompaction) {
+        observedAutomaticCompaction = false;
+        await sendCompactionNotice(Commands.TELEGRAM_COMPACTION_COMPLETED_TEXT);
+      }
     },
     async onAgentStart(event, ctx) {
       if (!isSessionContextActive(ctx)) return;

package/lib/commands.ts

@@ -185,6 +185,10 @@ export function formatTelegramCommandEmojiPrefix(
   return `${getTelegramCommandEmoji(command)} `;
 }
 
+export const TELEGRAM_COMPACTION_STARTED_TEXT =
+  `${formatTelegramCommandEmojiPrefix("compact")}Compaction started.`;
+export const TELEGRAM_COMPACTION_COMPLETED_TEXT = "✅ Compaction completed.";
+
 function formatTelegramBotCommandDescription(
   command: TelegramCommandEmojiName,
   description: string,
@@ -716,7 +720,10 @@ export interface TelegramCommandTargetRuntimeDeps<TContext> {
     chatId: number,
     replyToMessageId: number,
     text: string,
-    options?: { target?: { chatId: number; threadId?: number } },
+    options?: {
+      parseMode?: "HTML";
+      target?: { chatId: number; threadId?: number };
+    },
   ) => Promise<unknown>;
 }
 
@@ -734,7 +741,11 @@ export interface TelegramCommandTargetRuntime<
   showStatus: (message: TMessage, ctx: TContext) => Promise<void>;
   openModelMenu: (message: TMessage, ctx: TContext) => Promise<void>;
   openSettingsMenu: (message: TMessage, ctx: TContext) => Promise<void>;
-  sendTextReply: (message: TMessage, text: string) => Promise<void>;
+  sendTextReply: (
+    message: TMessage,
+    text: string,
+    options?: { parseMode?: "HTML" },
+  ) => Promise<void>;
 }
 
 export function getTelegramCommandMessageTarget(
@@ -917,9 +928,10 @@ export function createTelegramCommandTargetRuntime<
         target.threadId,
       );
     },
-    sendTextReply: async (message, text) => {
+    sendTextReply: async (message, text, options) => {
       const target = getTelegramCommandMessageTarget(message);
       await deps.sendTextReply(target.chatId, target.replyToMessageId, text, {
+        ...options,
         target,
       });
     },
@@ -1002,7 +1014,11 @@ export interface TelegramCommandRuntimeDeps<
   registerBotCommands: () => Promise<void>;
   getPromptTemplateCommands?: () => readonly TelegramPromptTemplateMenuCommand[];
   persistConfig: () => Promise<void>;
-  sendTextReply: (message: TMessage, text: string) => Promise<void>;
+  sendTextReply: (
+    message: TMessage,
+    text: string,
+    options?: { parseMode?: "HTML" },
+  ) => Promise<void>;
   sendInteractiveMessage?: TelegramCompactConfirmationDeps["sendInteractiveMessage"];
   assertExecutionCurrent?: (message: TMessage) => void;
 }
@@ -1185,11 +1201,14 @@ export async function handleTelegramNextCommand(deps: {
   dispatchNextQueuedTurn: () => void;
   clearFoldForDispatch: () => void;
   updateStatus: () => void;
-  sendTextReply: (text: string) => Promise<void>;
+  sendTextReply: (
+    text: string,
+    options?: { parseMode?: "HTML" },
+  ) => Promise<void>;
 }): Promise<void> {
   deps.clearPendingModelSwitch();
   if (!deps.hasQueuedItems()) {
-    await deps.sendTextReply("**Queue is empty.**");
+    await deps.sendTextReply("<b>Queue is empty.</b>", { parseMode: "HTML" });
     return;
   }
   if (!deps.isIdle() && deps.hasAbortHandler()) {
@@ -1294,7 +1313,7 @@ export async function handleTelegramCompactConfirmationCallback<TContext>(
   await deps.editInteractiveMessage(
     chatId,
     messageId,
-    `${formatTelegramCommandEmojiPrefix("compact")}Compaction started.`,
+    TELEGRAM_COMPACTION_STARTED_TEXT,
     "plain",
     { inline_keyboard: [] },
   );
@@ -1335,7 +1354,7 @@ export async function handleTelegramCompactCommand(
         deps.setCompactionInProgress(false);
         deps.updateStatus();
         dispatchNextQueuedTelegramTurnAfterCompact(deps);
-        void deps.sendTextReply("✅ Compaction completed.");
+        void deps.sendTextReply(TELEGRAM_COMPACTION_COMPLETED_TEXT);
       },
       onError: (error) => {
         deps.stopTypingLoop?.();
@@ -1358,7 +1377,7 @@ export async function handleTelegramCompactCommand(
   }
   if (!deps.suppressStartNotice) {
     await deps.sendTextReply(
-      `${formatTelegramCommandEmojiPrefix("compact")}Compaction started.`,
+      TELEGRAM_COMPACTION_STARTED_TEXT,
     );
   }
 }
@@ -1631,11 +1650,13 @@ async function handleTelegramCommandRuntime<
 ): Promise<boolean> {
   const assertExecutionCurrentFor = (nextMessage: TMessage) => (): void =>
     deps.assertExecutionCurrent?.(nextMessage);
-  const sendReplyFor = (nextMessage: TMessage) => async (text: string) => {
-    deps.assertExecutionCurrent?.(nextMessage);
-    await deps.sendTextReply(nextMessage, text);
-    deps.assertExecutionCurrent?.(nextMessage);
-  };
+  const sendReplyFor =
+    (nextMessage: TMessage) =>
+    async (text: string, options?: { parseMode?: "HTML" }) => {
+      deps.assertExecutionCurrent?.(nextMessage);
+      await deps.sendTextReply(nextMessage, text, options);
+      deps.assertExecutionCurrent?.(nextMessage);
+    };
   const updateStatusFor = (commandCtx: TContext) => () =>
     deps.updateStatus(commandCtx);
   return executeTelegramCommandAction(

package/lib/status.ts

@@ -1505,6 +1505,7 @@ function buildContextSummary(
 }
 
 function buildStatusSummary(ctx: TelegramStatusContext): string {
+  if (ctx.isCompactionInProgress?.()) return "compacting";
   if (ctx.hasPendingMessages?.()) return "pending";
   if (ctx.isIdle?.() === false) return "active";
   if (ctx.isIdle?.() === true) return "idle";

package/package.json

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

package/skills/generated-control-surface/SKILL.md

@@ -80,6 +80,8 @@ A surface normally contains:
 
 Prefer 2–6 controls for feedback and decisions; navigation collections may use up to 12 when the additional entries remain scannable. Split larger sets by category or page instead of building a button wall. Do not add navigation controls when the surface is a one-step decision.
 
+Present compact metadata as stacked key-value rows that reuse status-surface grammar: a short bold label, a colon, and an inline-code value when the value is path-like, numeric, an identifier, or machine state. Prefer ``**Path:** `/home/llb` `` and ``**Entries:** `1–10 of 52` `` on separate lines over prose fragments joined by a middle dot or other decorative section separator.
+
 ## Truth Modes
 
 Name the basis of the surface when ambiguity matters:
@@ -146,8 +148,8 @@ Treat a user prompt that is exactly a plausible filesystem path—including `/`
 
 1. Pin `⬆️ Up` as the first full-width row whenever the current path is not filesystem root; its entire prompt is the exact parent path. Omit Up at `/`.
 2. When page traversal exists, place `⬅️ Previous` and `➡️ Next` together in one compact row immediately after Up, omitting either unavailable direction. Page traversal re-inspects the directory and preserves a fixed 10-entry page size; moving Up opens the parent at page one.
-3. Render at most 10 alphabetically ordered entry buttons as full-width rows after structural navigation. Each label uses the entry name plus a semantic folder/file emoji, and its entire prompt may be the exact target path because this Skill defines path-only prompts as navigation intent.
-4. Keep visible text to a compact path and range summary such as `📁 /home/llb · 1–10 of 52`; do not duplicate entry names as a plain or monospaced directory listing. Omit Refresh by default because resubmitting the current path already requests fresh rendering.
+3. Sort entries by semantic category before pagination: visible directories, hidden directories, visible files, then hidden files; sort names alphabetically within each category. Render at most 10 resulting entry buttons as full-width rows after structural navigation. Each label uses the entry name plus a semantic folder/file emoji, and its entire prompt may be the exact target path because this Skill defines path-only prompts as navigation intent.
+4. Keep visible text to two compact status-style rows such as ``**Path:** `/home/llb` `` and ``**Entries:** `1–10 of 52` ``; do not join metadata with a middle dot and do not duplicate entry names as a plain or monospaced directory listing. Omit Refresh by default because resubmitting the current path already requests fresh rendering.
 
 For pi-telegram, emit the complete filesystem control set—Up, compact page traversal, then current-page entries—in one `telegram_button` JSON matrix rather than repeating one hidden comment per button. If prompt buttons are unavailable or fail to render, preserve the same ordering and pagination as an ordinary numbered text fallback, not a monospaced inventory, so free-form path entry remains sufficient. Show a plain or monospaced directory listing instead only when the user explicitly requests it or durable user Knowledge establishes that presentation preference. Never preview credential stores, private keys, browser profiles, cookies, tokens, wallets, or other secret-bearing files, and never raise privileges merely to enumerate a path.