@llblab/pi-kit 0.1.13 → 0.2.0

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

@@ -105,7 +105,6 @@ export interface TelegramConfig {
   assistant?: {
     draftPreviews?: boolean;
     rendering?: TelegramAssistantRenderingMode;
-    proactivePush?: boolean;
     activity?: TelegramActivityVerbosity;
     timeInjection?: TelegramTimeMode;
     /** @deprecated use activity */
@@ -454,10 +453,32 @@ function omitTelegramRootProfileFields(config: TelegramConfig): TelegramConfig {
   return sharedConfig;
 }
 
+function omitRetiredProactivePush(config: TelegramConfig): {
+  config: TelegramConfig;
+  changed: boolean;
+} {
+  const assistant = config.assistant as
+    | (NonNullable<TelegramConfig["assistant"]> & { proactivePush?: unknown })
+    | undefined;
+  if (!assistant || !Object.hasOwn(assistant, "proactivePush")) {
+    return { config, changed: false };
+  }
+  const { proactivePush: _proactivePush, ...remainingAssistant } = assistant;
+  const next = { ...config };
+  if (Object.keys(remainingAssistant).length > 0) {
+    next.assistant = remainingAssistant;
+  } else {
+    delete next.assistant;
+  }
+  return { config: next, changed: true };
+}
+
 export function normalizeTelegramDefaultProfileConfig(config: TelegramConfig): {
   config: TelegramConfig;
   changed: boolean;
 } {
+  const retiredProactivePush = omitRetiredProactivePush(config);
+  config = retiredProactivePush.config;
   const hasLegacyRootProfile = [
     "botToken",
     "botUsername",
@@ -465,7 +486,9 @@ export function normalizeTelegramDefaultProfileConfig(config: TelegramConfig): {
     "allowedUserId",
     "lastUpdateId",
   ].some((field) => Object.hasOwn(config, field));
-  if (!hasLegacyRootProfile) return { config, changed: false };
+  if (!hasLegacyRootProfile) {
+    return { config, changed: retiredProactivePush.changed };
+  }
   const canonicalProfile = config.profiles?.[TELEGRAM_DEFAULT_PROFILE_NAME];
   const legacyToken = config.botToken?.trim();
   if (Object.hasOwn(config, "botToken") && !legacyToken) {
@@ -712,27 +735,6 @@ export function createTelegramConfigStore(
   };
 }
 
-export function createTelegramProactivePushChecker(
-  configStore: Pick<TelegramConfigStore, "get">,
-): () => boolean {
-  return () => configStore.get().assistant?.proactivePush ?? true;
-}
-
-export function createTelegramProactivePushSetter(
-  configStore: TelegramMutableConfigStore,
-): (enabled: boolean) => Promise<void> {
-  return async (enabled) => {
-    await loadLatestTelegramConfig(configStore);
-    const current = configStore.get();
-    const config: TelegramConfig = {
-      ...current,
-      assistant: { ...current.assistant, proactivePush: enabled },
-    };
-    configStore.set(config);
-    await configStore.persist(config);
-  };
-}
-
 export function createTelegramDraftPreviewsChecker(
   configStore: Pick<TelegramConfigStore, "get">,
 ): () => boolean {
@@ -1019,8 +1021,6 @@ export function createTelegramConfigControls(
   configStore: TelegramMutableConfigStore,
 ) {
   return {
-    isProactivePushEnabled: createTelegramProactivePushChecker(configStore),
-    setProactivePushEnabled: createTelegramProactivePushSetter(configStore),
     areDraftPreviewsEnabled: createTelegramDraftPreviewsChecker(configStore),
     setDraftPreviewsEnabled: createTelegramDraftPreviewsSetter(configStore),
     getAssistantRenderingMode:

package/node_modules/@llblab/pi-telegram/lib/menu-settings.ts

@@ -21,7 +21,6 @@ import type { TelegramVoiceReplyMode } from "./voice.ts";
 export type TelegramSettingsMenuReplyMarkup = TelegramInlineKeyboardMarkup;
 
 export interface TelegramSettingsStateDeps {
-  isProactivePushEnabled: () => boolean;
   areDraftPreviewsEnabled: () => boolean;
   getAssistantRenderingMode: () => TelegramAssistantRenderingMode;
   getActivityVerbosity: () => TelegramActivityVerbosity;
@@ -32,7 +31,6 @@ export interface TelegramSettingsStateDeps {
 }
 
 export interface TelegramSettingsMutationDeps extends TelegramSettingsStateDeps {
-  setProactivePushEnabled: (enabled: boolean) => Promise<void>;
   setDraftPreviewsEnabled: (enabled: boolean) => Promise<void>;
   setAssistantRenderingMode: (
     mode: TelegramAssistantRenderingMode,
@@ -139,7 +137,6 @@ export interface TelegramSettingsMenuRuntimeDeps<
 export const SETTINGS_MENU_TITLE = "<b>⚙️ Settings:</b>";
 export const AUTOMATIC_THREAD_CLEANUP_SETTINGS_TITLE =
   "<b>🧹 Thread cleanup:</b>";
-export const PROACTIVE_PUSH_SETTINGS_TITLE = "<b>📌 Proactive push:</b>";
 export const DRAFT_PREVIEWS_SETTINGS_TITLE = "<b>📝 Draft previews:</b>";
 export const ASSISTANT_RENDERING_SETTINGS_TITLE =
   "<b>🧾 Assistant rendering:</b>";
@@ -181,19 +178,6 @@ export function buildAutomaticThreadCleanupSettingsText(
   ].join("\n");
 }
 
-export function buildProactivePushSettingsText(
-  proactivePushEnabled: boolean,
-): string {
-  return [
-    `${PROACTIVE_PUSH_SETTINGS_TITLE} <code>${proactivePushEnabled ? "on" : "off"}</code>`,
-    "",
-    "Control whether public assistant output from local/autonomous work is projected to Telegram.",
-    "",
-    "<code>-</code> <code>on</code> (default): send each completed public block, including visible checkpoints and the final answer, while connected.",
-    "<code>-</code> <code>off</code>: keep local/autonomous assistant blocks in Pi; Telegram-originated replies still use their normal delivery path.",
-  ].join("\n");
-}
-
 export function buildDraftPreviewsSettingsText(enabled: boolean): string {
   return [
     `${DRAFT_PREVIEWS_SETTINGS_TITLE} <code>${enabled ? "on" : "off"}</code>`,
@@ -265,7 +249,6 @@ export function buildTimeInjectionModeSettingsText(
 }
 
 export function buildTelegramSettingsMenuReplyMarkup(
-  proactivePushEnabled: boolean,
   draftPreviewsEnabled: boolean,
   assistantRenderingModeOrVoiceReplyMode:
     TelegramAssistantRenderingMode | TelegramVoiceReplyMode,
@@ -325,10 +308,6 @@ export function buildTelegramSettingsMenuReplyMarkup(
       text: `🔬 Activity: ${activityVerbosity}`,
       callback_data: "settings:open:activity-verbosity",
     },
-    {
-      text: `📌 Proactive push: ${proactivePushEnabled ? "on" : "off"}`,
-      callback_data: "settings:open:proactive",
-    },
     {
       text: `🕒 Time injection: ${getTelegramSettingsStateValueLabel(timeInjectionMode)}`,
       callback_data: "settings:open:time-injection",
@@ -362,7 +341,6 @@ export async function openTelegramSettingsMenu<
     state,
     buildTelegramSettingsMenuText(),
     buildTelegramSettingsMenuReplyMarkup(
-      deps.isProactivePushEnabled(),
       deps.areDraftPreviewsEnabled(),
       deps.getAssistantRenderingMode(),
       deps.getVoiceReplyMode(),
@@ -399,26 +377,6 @@ export function buildAutomaticThreadCleanupSettingsReplyMarkup(
   };
 }
 
-export function buildProactivePushSettingsReplyMarkup(
-  proactivePushEnabled: boolean,
-): TelegramSettingsMenuReplyMarkup {
-  return {
-    inline_keyboard: [
-      [{ text: "⬆️ Back", callback_data: "settings:list" }],
-      [
-        {
-          text: proactivePushEnabled ? "🟢 On" : "⚫️ On",
-          callback_data: "settings:set:proactive:on",
-        },
-        {
-          text: proactivePushEnabled ? "⚫️ Off" : "🟡 Off",
-          callback_data: "settings:set:proactive:off",
-        },
-      ],
-    ],
-  };
-}
-
 export function buildDraftPreviewsSettingsReplyMarkup(
   enabled: boolean,
 ): TelegramSettingsMenuReplyMarkup {
@@ -521,7 +479,6 @@ export async function updateTelegramSettingsMenuMessage(
   await deps.updateSettingsMessage(
     buildTelegramSettingsMenuText(),
     buildTelegramSettingsMenuReplyMarkup(
-      deps.isProactivePushEnabled(),
       deps.areDraftPreviewsEnabled(),
       deps.getAssistantRenderingMode(),
       deps.getVoiceReplyMode(),
@@ -544,16 +501,6 @@ export async function updateAutomaticThreadCleanupSettingsMessage(
   );
 }
 
-export async function updateProactivePushSettingsMessage(
-  deps: TelegramSettingsMenuCallbackDeps,
-): Promise<void> {
-  const proactivePushEnabled = deps.isProactivePushEnabled();
-  await deps.updateSettingsMessage(
-    buildProactivePushSettingsText(proactivePushEnabled),
-    buildProactivePushSettingsReplyMarkup(proactivePushEnabled),
-  );
-}
-
 export async function updateDraftPreviewsSettingsMessage(
   deps: TelegramSettingsMenuCallbackDeps,
 ): Promise<void> {
@@ -621,9 +568,16 @@ export async function handleTelegramSettingsMenuCallbackAction(
     await deps.answerCallbackQuery(callbackQueryId);
     return true;
   }
-  if (data === "settings:open:proactive") {
-    await updateProactivePushSettingsMessage(deps);
-    await deps.answerCallbackQuery(callbackQueryId);
+  if (
+    data === "settings:open:proactive" ||
+    data === "settings:set:proactive:on" ||
+    data === "settings:set:proactive:off"
+  ) {
+    await updateTelegramSettingsMenuMessage(deps, deps.sectionRegistry);
+    await deps.answerCallbackQuery(
+      callbackQueryId,
+      "Public assistant output is always delivered while Telegram is connected.",
+    );
     return true;
   }
   if (
@@ -751,19 +705,6 @@ export async function handleTelegramSettingsMenuCallbackAction(
     );
     return true;
   }
-  if (
-    data === "settings:set:proactive:on" ||
-    data === "settings:set:proactive:off"
-  ) {
-    const enabled = data.endsWith(":on");
-    await deps.setProactivePushEnabled(enabled);
-    await updateProactivePushSettingsMessage(deps);
-    await deps.answerCallbackQuery(
-      callbackQueryId,
-      `Proactive push ${enabled ? "enabled" : "disabled"}`,
-    );
-    return true;
-  }
   await deps.answerCallbackQuery(callbackQueryId);
   return true;
 }
@@ -781,7 +722,6 @@ export function createTelegramSettingsMenuRuntime<
       return openTelegramSettingsMenu(
         {
           getModelMenuState: () => deps.getModelMenuState(chatId, ctx),
-          isProactivePushEnabled: deps.isProactivePushEnabled,
           areDraftPreviewsEnabled: deps.areDraftPreviewsEnabled,
           getAssistantRenderingMode: deps.getAssistantRenderingMode,
           getActivityVerbosity: deps.getActivityVerbosity,
@@ -805,7 +745,6 @@ export function createTelegramSettingsMenuRuntime<
       await deps.reloadConfig?.();
       return updateTelegramSettingsMenuMessage(
         {
-          isProactivePushEnabled: deps.isProactivePushEnabled,
           areDraftPreviewsEnabled: deps.areDraftPreviewsEnabled,
           getAssistantRenderingMode: deps.getAssistantRenderingMode,
           getActivityVerbosity: deps.getActivityVerbosity,
@@ -849,7 +788,6 @@ export function createTelegramSettingsMenuRuntime<
         deps.storeModelMenuState(state);
       }
       return handleTelegramSettingsMenuCallbackAction(query.id, query.data, {
-        isProactivePushEnabled: deps.isProactivePushEnabled,
         areDraftPreviewsEnabled: deps.areDraftPreviewsEnabled,
         getAssistantRenderingMode: deps.getAssistantRenderingMode,
         getActivityVerbosity: deps.getActivityVerbosity,
@@ -857,7 +795,6 @@ export function createTelegramSettingsMenuRuntime<
         isVoiceReplyModeConfigured: deps.isVoiceReplyModeConfigured,
         getTimeInjectionMode: deps.getTimeInjectionMode,
         isAutomaticThreadCleanupEnabled: deps.isAutomaticThreadCleanupEnabled,
-        setProactivePushEnabled: deps.setProactivePushEnabled,
         setDraftPreviewsEnabled: deps.setDraftPreviewsEnabled,
         setAssistantRenderingMode: deps.setAssistantRenderingMode,
         setActivityVerbosity: deps.setActivityVerbosity,

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

@@ -14,6 +14,7 @@ export interface TelegramUsageStats {
   totalCacheRead: number;
   totalCacheWrite: number;
   totalCost: number;
+  latestCacheHitRate?: number;
 }
 
 interface TelegramUsageMessage {
@@ -1473,6 +1474,9 @@ function collectUsageStats(ctx: TelegramStatusContext): TelegramUsageStats {
     stats.totalCacheRead += usage.cacheRead;
     stats.totalCacheWrite += usage.cacheWrite;
     stats.totalCost += usage.cost.total;
+    const promptTokens = usage.input + usage.cacheRead + usage.cacheWrite;
+    stats.latestCacheHitRate =
+      promptTokens > 0 ? (usage.cacheRead / promptTokens) * 100 : undefined;
   }
   return stats;
 }
@@ -1494,6 +1498,12 @@ function buildUsageSummary(stats: TelegramUsageStats): string | undefined {
     tokenParts.push(`R${formatTokens(stats.totalCacheRead)}`);
   if (stats.totalCacheWrite)
     tokenParts.push(`W${formatTokens(stats.totalCacheWrite)}`);
+  if (
+    (stats.totalCacheRead > 0 || stats.totalCacheWrite > 0) &&
+    stats.latestCacheHitRate !== undefined
+  ) {
+    tokenParts.push(`CH${stats.latestCacheHitRate.toFixed(1)}%`);
+  }
   return tokenParts.length > 0 ? tokenParts.join(" ") : undefined;
 }
 
@@ -1549,7 +1559,7 @@ export function buildStatusHtml(
   const usageSummary = buildUsageSummary(stats);
   const costSummary = buildCostSummary(stats, usesSubscription);
   if (usageSummary) {
-    lines.push(buildStatusRow("Usage", usageSummary));
+    lines.push(buildStatusRow("Tokens", usageSummary));
   }
   if (costSummary) {
     lines.push(buildStatusRow("Cost", costSummary));

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

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

package/node_modules/@llblab/pi-telegram/skills/generated-control-surface/SKILL.md

@@ -136,11 +136,11 @@ Use the transport's canonical prompt-button syntax. For pi-telegram, one top-lev
 
 Model the control surface as an ordered ragged sequence of independently sized rows, not as a rectangular matrix to fill. Rectangular grids are one specialization for genuinely spatial or coordinate-bearing state; most interfaces should vary row width according to hierarchy, grouping, label pressure, and action priority.
 
-- Default to one full-width button per row for non-spatial controls. Put controls in one compact row only when they are genuine peers that answer the same local question or form one coherent toolbar/navigation group **and** their rendered labels comfortably fit a narrow phone-width chat.
+- Default to one full-width button per row for non-spatial controls. In pi-telegram matrix syntax, emit these vertical controls as top-level cells without wrapping them in a nested row array. A nested array explicitly opts into horizontal grouping and is justified only when the controls are genuine peers and every label is unmistakably compact—roughly no more than 15 visible characters including its emoji and space. This is a judgment heuristic, not a request to mechanically count characters: if fit is uncertain, wording is multi-phrase, or truncation is plausible, keep top-level vertical buttons.
 - Use a singleton full-width row for a structurally independent, pinned, primary, summary, or high-consequence action, and whenever label length makes horizontal grouping cramped or ambiguous.
 - Vary row widths intentionally—for example `1 → 2 → 4 → 1 → 2`—and never pad a row with empty, duplicate, or no-op controls merely to produce uniform dimensions.
 - Preserve reading order across rows: orientation and structural navigation first, primary content or choices next, secondary controls afterward, and destructive actions visibly separated when present.
-- Treat two columns as an earned compact mode, not the default: a pair normally fits when each label is no more than one emoji plus roughly two average-length words. If either label has more words, unusually long words, qualifiers, or likely wrapping, place each button on its own row. Use at most two columns for readable text labels; move additional peer choices into more semantic rows rather than compressing textual buttons across a phone-width line. Three through five columns are for short symbols, glyphs, coordinates, or compact codes whose position carries meaning. Six through eight may be used only for single-glyph or similarly minimal position-bearing labels whose grouping materially improves the interaction; a row of emoji-only controls may therefore legitimately use up to eight columns. Eight is the phone-width UX maximum: never generate a row of nine or more controls even though the parser has no artificial width cap. Never shorten necessary wording merely to increase row density; regroup or use full-width rows when labels need explanation, wrap ambiguously, or lose meaning without prose.
+- Treat two columns as an earned compact exception, never the default: a pair normally fits only when each label is unmistakably short—approximately one emoji plus one or two short words and roughly 15 visible characters or fewer. Do not count mechanically to justify density. If either label has more words, unusually long words, qualifiers, or any plausible wrapping or ellipsis risk, place each button on its own top-level row. Use at most two columns for readable text labels; move additional peer choices into more semantic rows rather than compressing textual buttons across a phone-width line. Three through five columns are for short symbols, glyphs, coordinates, or compact codes whose position carries meaning. Six through eight may be used only for single-glyph or similarly minimal position-bearing labels whose grouping materially improves the interaction; a row of emoji-only controls may therefore legitimately use up to eight columns. Eight is the phone-width UX maximum: never generate a row of nine or more controls even though the parser has no artificial width cap. Never shorten necessary wording merely to increase row density; regroup or use full-width rows when labels need explanation, wrap ambiguously, or lose meaning without prose.
 
 Treat vertical extent independently from horizontal density. A genuinely spatial surface may retain many rows—such as an `8×16` field—when vertical continuity, coordinates, and one-glance topology matter; do not paginate merely to make its height match its width. For non-spatial collections, however, a tall button wall should yield to semantic grouping, progressive disclosure, or pagination. Keep compact state and instructions above a tall surface, preserve stable coordinates across regeneration, and avoid repeating prose between rows.
 
@@ -187,7 +187,7 @@ Button prompts must:
 - Request fresh inspection when state may have changed.
 - Avoid embedding volatile output that should be rediscovered.
 
-Labels stay short, distinct, and scannable. Prefer an explicit `label` over exposing a long prompt as button text. Emoji are explicitly allowed and encouraged when one consistent semantic marker improves scanning or expressiveness; keep their meaning consistent across sibling controls, avoid decorative noise, and do not rely on emoji or color alone. If buttons are unavailable, render the same control surface as a numbered choice list.
+Labels stay short, distinct, and scannable. Prefer an explicit `label` over exposing a long prompt as button text. Every generated human-readable action label must start with the most semantically appropriate emoji, followed by one ASCII space and concise action text; selecting that emoji is a required design step, not optional polish. When label and prompt are intentionally identical, use the same emoji-prefixed value rather than dropping the marker through compact syntax. Keep emoji meaning consistent across sibling controls, avoid decorative noise, and do not rely on emoji or color alone. An emoji-free text label remains a transport-compatible fallback only when no honest semantic emoji can be identified after considering the action, domain, and state; convenience, label pressure, or uncertainty between several reasonable candidates is not sufficient. Genuine coordinates, established symbolic controls, and intentionally emoji-only spatial cells keep their domain grammar. If buttons are unavailable, render the same control surface as a numbered choice list.
 
 ## Capability Adapters
 
@@ -243,6 +243,8 @@ Before sending a surface, verify:
 - Complete versus filtered or adapted output is labeled honestly.
 - No secret appears in visible text or button payloads.
 - Every button carries a valid self-contained next intent and measurably shortens likely feedback.
+- Every human-readable action label uses `emoji + space + text`; an emoji-free fallback has an explicit semantic reason rather than mere convenience.
+- Non-spatial action buttons are top-level vertical cells by default; every nested row has an obvious compact-peer justification with no plausible truncation risk.
 - The surface preserves free-form feedback when choices are not exhaustive.
 - High-impact operations route through confirmation.
 - Back/Up and Refresh appear only when useful.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-kit",
-  "version": "0.1.13",
+  "version": "0.2.0",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -40,10 +40,10 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@llblab/pi-actors": "0.50.0",
+    "@llblab/pi-actors": "0.52.0",
     "@llblab/pi-codex-usage": "0.9.4",
     "@llblab/pi-grow-loop": "0.7.3",
-    "@llblab/pi-telegram": "0.40.0"
+    "@llblab/pi-telegram": "0.41.0"
   },
   "bundledDependencies": [
     "@llblab/pi-actors",