@llblab/pi-telegram 0.11.2 → 0.13.0

package/lib/config.ts

@@ -1,7 +1,7 @@
 /**
  * Telegram bridge config and pairing helpers
  * Zones: telegram config, pairing, filesystem
- * Owns persisted bot/session pairing state, local config storage, authorization policy, and first-user pairing side effects
+ * Owns persisted bot/session pairing state, local config storage, live config controls, authorization policy, and first-user pairing side effects
  */
 
 import { existsSync } from "node:fs";
@@ -9,7 +9,7 @@ import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 
-import type { TelegramInboundHandlerConfig } from "./inbound-handlers.ts";
+import type { TelegramInboundHandlerConfig } from "./inbound.ts";
 import type { CommandTemplateObjectConfig } from "./command-templates.ts";
 
 const CONFIG_RUNTIME_KEY = "__piTelegramConfigRuntime__";
@@ -30,9 +30,8 @@ export type TelegramOutboundCommandTemplateConfig =
 export interface TelegramOutboundHandlerConfig extends CommandTemplateObjectConfig {
   type?: string;
   match?: string | string[];
-  pipe?: TelegramOutboundCommandTemplateConfig[];
   output?: string;
-  timeout?: number;
+  timeout?: number | string;
 }
 
 export type TelegramTimeMode = "hidden" | "always" | "interval";
@@ -110,6 +109,22 @@ export function updateTelegramVoiceConfig(
   return true;
 }
 
+export function bindGlobalTelegramConfigRuntime(
+  configStore: Pick<TelegramConfigStore, "get" | "set" | "persist">,
+): void {
+  setGlobalTelegramConfigRuntime({
+    updateVoiceConfig(voice) {
+      const current = configStore.get();
+      const next = {
+        ...current,
+        voice: { ...(current.voice ?? {}), ...voice },
+      };
+      configStore.set(next);
+      void configStore.persist(next);
+    },
+  });
+}
+
 export async function readTelegramConfig(
   configPath: string,
 ): Promise<TelegramConfig> {
@@ -266,6 +281,16 @@ export function createTelegramTimeInjectionModeSetter(
 ): (injectionMode: TelegramTimeMode) => Promise<void> {
   return async (injectionMode) => {
     const current = configStore.get();
+    if (injectionMode === "hidden") {
+      const { injectionMode: _injectionMode, ...remainingTime } =
+        current.time ?? {};
+      const next = { ...current };
+      if (Object.keys(remainingTime).length > 0) next.time = remainingTime;
+      else delete next.time;
+      configStore.set(next);
+      await configStore.persist(next);
+      return;
+    }
     const next = {
       ...current,
       time: { ...(current.time ?? {}), injectionMode },
@@ -282,6 +307,21 @@ export function createTelegramProactivePushChatIdGetter(deps: {
   return () => deps.getActiveTurnChatId() ?? deps.getAllowedUserId();
 }
 
+export function createTelegramConfigControls(
+  configStore: Pick<TelegramConfigStore, "get" | "set" | "persist">,
+) {
+  return {
+    isProactivePushEnabled: createTelegramProactivePushChecker(configStore),
+    setProactivePushEnabled: createTelegramProactivePushSetter(configStore),
+    getVoiceReplyMode: createTelegramVoiceReplyModeGetter(configStore),
+    isVoiceReplyModeConfigured:
+      createTelegramVoiceReplyModeConfiguredChecker(configStore),
+    setVoiceReplyMode: createTelegramVoiceReplyModeSetter(configStore),
+    getTimeInjectionMode: createTelegramTimeInjectionModeGetter(configStore),
+    setTimeInjectionMode: createTelegramTimeInjectionModeSetter(configStore),
+  };
+}
+
 export type TelegramAuthorizationState =
   | { kind: "pair"; userId: number }
   | { kind: "allow" }

package/lib/{inbound-handlers.ts → inbound.ts}

@@ -11,6 +11,7 @@ import {
   buildCommandTemplateInvocation,
   expandCommandTemplateConfigs,
   normalizeCommandTemplateConfig,
+  substituteCommandTemplateToken,
   type CommandTemplateConfig,
   type CommandTemplateObjectConfig,
 } from "./command-templates.ts";
@@ -28,10 +29,9 @@ export interface TelegramInboundHandlerConfig {
   mime?: string | string[];
   type?: string | string[];
   template?: string | TelegramInboundCommandTemplateConfig[];
-  pipe?: TelegramInboundCommandTemplateConfig[];
   args?: string[];
   defaults?: Record<string, unknown>;
-  timeout?: number;
+  timeout?: number | string;
 }
 
 export interface TelegramInboundHandlerFile {
@@ -62,6 +62,7 @@ export interface TelegramInboundHandlerExecOptions {
   timeout?: number;
   signal?: AbortSignal;
   stdin?: string;
+  retry?: number;
 }
 
 export interface TelegramInboundHandlerExecResult {
@@ -216,9 +217,7 @@ function matchesWildcard(pattern: string, value: string | undefined): boolean {
   return new RegExp(`^${escaped}$`).test(normalizedValue);
 }
 
-function handlerHasSelectors(
-  handler: TelegramInboundHandlerConfig,
-): boolean {
+function handlerHasSelectors(handler: TelegramInboundHandlerConfig): boolean {
   return (
     normalizeStringList(handler.match).length > 0 ||
     normalizeStringList(handler.mime).length > 0 ||
@@ -324,13 +323,28 @@ export function buildTelegramInboundHandlerInvocation(
   );
 }
 
+function resolveTelegramInboundNumericControlField(
+  value: number | string | undefined,
+  values: Record<string, unknown>,
+  label: string,
+): number | undefined {
+  if (value === undefined) return undefined;
+  const resolved =
+    typeof value === "string"
+      ? substituteCommandTemplateToken(value, values, label)
+      : value;
+  if (resolved === "") return undefined;
+  const numeric = Number(resolved);
+  if (!Number.isFinite(numeric) || numeric < 0)
+    throw new Error(`Command template ${label} must be a non-negative number.`);
+  return numeric;
+}
+
 function getTelegramInboundHandlerConfiguredTimeout(
   handler: TelegramInboundCommandTemplateConfig,
 ): number | undefined {
   const timeout = typeof handler === "string" ? undefined : handler.timeout;
-  return typeof timeout === "number" && Number.isFinite(timeout) && timeout > 0
-    ? timeout
-    : undefined;
+  return resolveTelegramInboundNumericControlField(timeout, {}, "timeout");
 }
 
 function getTelegramInboundHandlerTimeout(
@@ -376,8 +390,7 @@ function getTelegramInboundCompositionStepTimeout(
 function getTelegramInboundHandlerKind(
   handler: TelegramInboundHandlerConfig,
 ): string {
-  if (Array.isArray(handler.template) || handler.pipe?.length)
-    return "composition";
+  if (Array.isArray(handler.template)) return "composition";
   if (handler.template) return "template";
   return "unknown";
 }
@@ -412,7 +425,7 @@ async function executeTelegramInboundHandlerInvocation(
     cwd,
     timeout,
     ...(typeof handler === "object" && handler.retry !== undefined
-      ? { retry: handler.retry }
+      ? { retry: resolveTelegramInboundNumericControlField(handler.retry, {}, "retry") }
       : {}),
     ...(stdin !== undefined ? { stdin } : {}),
   });
@@ -429,12 +442,6 @@ function getTelegramInboundHandlerCompositionSteps(
       handler,
     ) as TelegramInboundCommandTemplateConfig[];
   }
-  if (handler.pipe?.length) {
-    return expandCommandTemplateConfigs({
-      ...handler,
-      template: handler.pipe,
-    }) as TelegramInboundCommandTemplateConfig[];
-  }
   return [];
 }
 
@@ -492,7 +499,7 @@ async function executeTelegramTextHandlerInvocation(
     timeout,
     stdin: text,
     ...(typeof handler === "object" && handler.retry !== undefined
-      ? { retry: handler.retry }
+      ? { retry: resolveTelegramInboundNumericControlField(handler.retry, {}, "retry") }
       : {}),
   });
   if (result.code !== 0)
@@ -526,7 +533,7 @@ async function executeTelegramTextHandler(
           : getTelegramInboundCompositionStepTimeout(handler, step, startedAt),
       );
     } catch (error) {
-      if (typeof step === "object" && step.critical) throw error;
+      if (typeof step === "object" && step.failure === "root") throw error;
       output = "";
     }
     if (index > 0 && !output) output = text;
@@ -642,7 +649,10 @@ async function readBuiltInTelegramTextAttachment(
   if (!isTelegramTextMimeType(file.mimeType)) return undefined;
   const content = await readFile(file.path, "utf8");
   const normalized = content.trim();
-  if (!normalized || Buffer.byteLength(normalized, "utf8") > BUILT_IN_TEXT_ATTACHMENT_MAX_BYTES) {
+  if (
+    !normalized ||
+    Buffer.byteLength(normalized, "utf8") > BUILT_IN_TEXT_ATTACHMENT_MAX_BYTES
+  ) {
     return undefined;
   }
   const name = file.fileName || basename(file.path);
@@ -681,7 +691,7 @@ async function executeTelegramInboundHandler(
         index === 0 ? undefined : output,
       );
     } catch (error) {
-      if (typeof step === "object" && step.critical) throw error;
+      if (typeof step === "object" && step.failure === "root") throw error;
       output = "";
     }
   }

package/lib/lifecycle.ts

@@ -1,7 +1,7 @@
 /**
  * Telegram lifecycle hook registration helpers
  * Zones: pi agent lifecycle, telegram session
- * Owns binding prepared Telegram lifecycle runtimes to pi extension lifecycle events
+ * Binds prepared Telegram lifecycle runtimes to pi extension lifecycle events
  */
 
 import type {
@@ -107,16 +107,15 @@ type TelegramLifecycleTimer = number | ReturnType<typeof setTimeout>;
 export interface TelegramCompactionObserverRuntimeDeps<TContext> {
   setCompactionInProgress: (inProgress: boolean) => void;
   updateStatus: (ctx: TContext) => void;
+  startTypingLoop?: (ctx: TContext) => void;
+  stopTypingLoop?: () => void;
   requestDeferredDispatchNextQueuedTelegramTurn: (
     dispatch: (ctx: TContext) => void,
   ) => void;
   dispatchNextQueuedTelegramTurn: (ctx: TContext) => void;
   recordRuntimeEvent?: (category: string, error: unknown) => void;
   timeoutMs?: number;
-  setTimer?: (
-    callback: () => void,
-    ms: number,
-  ) => TelegramLifecycleTimer;
+  setTimer?: (callback: () => void, ms: number) => TelegramLifecycleTimer;
   clearTimer?: (timer: TelegramLifecycleTimer) => void;
 }
 
@@ -149,11 +148,13 @@ export function createTelegramCompactionObserverRuntime<TContext>(
   return {
     onSessionBeforeCompact: (_event, ctx) => {
       deps.setCompactionInProgress(true);
+      deps.startTypingLoop?.(ctx);
       deps.updateStatus(ctx);
       clearFallbackTimer();
       fallbackTimer = setTimer(() => {
         fallbackTimer = undefined;
         deps.setCompactionInProgress(false);
+        deps.stopTypingLoop?.();
         deps.updateStatus(ctx);
         deps.recordRuntimeEvent?.(
           "compact",
@@ -165,10 +166,44 @@ export function createTelegramCompactionObserverRuntime<TContext>(
     onSessionCompact: (_event, ctx) => {
       clearFallbackTimer();
       deps.setCompactionInProgress(false);
+      deps.stopTypingLoop?.();
       deps.updateStatus(ctx);
       requestDispatch();
     },
-    onSessionShutdown: clearFallbackTimer,
+    onSessionShutdown: () => {
+      clearFallbackTimer();
+      deps.stopTypingLoop?.();
+    },
+  };
+}
+
+export interface TelegramMessageActivityTypingDeps<TContext> {
+  hasActiveTurn: () => boolean;
+  startTypingLoop: (ctx: TContext) => void;
+  onMessageStart: TelegramLifecycleRegistrationDeps["onMessageStart"];
+  onMessageUpdate: TelegramLifecycleRegistrationDeps["onMessageUpdate"];
+}
+
+export function createTelegramMessageActivityTypingHooks<
+  TContext extends ExtensionContext,
+>(
+  deps: TelegramMessageActivityTypingDeps<TContext>,
+): Pick<
+  TelegramLifecycleRegistrationDeps,
+  "onMessageStart" | "onMessageUpdate"
+> {
+  const ensureTyping = (ctx: TContext): void => {
+    if (deps.hasActiveTurn()) deps.startTypingLoop(ctx);
+  };
+  return {
+    onMessageStart: async (event, ctx) => {
+      ensureTyping(ctx as TContext);
+      await deps.onMessageStart(event, ctx);
+    },
+    onMessageUpdate: async (event, ctx) => {
+      ensureTyping(ctx as TContext);
+      await deps.onMessageUpdate(event, ctx);
+    },
   };
 }
 

package/lib/locks.ts

@@ -125,7 +125,10 @@ export function writeLocks(path: string, locks: Record<string, unknown>): void {
   mkdirSync(dirname(path), { recursive: true });
   const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
   try {
-    writeFileSync(tempPath, `${JSON.stringify(locks, null, 2)}\n`, "utf8");
+    writeFileSync(tempPath, `${JSON.stringify(locks, null, 2)}\n`, {
+      encoding: "utf8",
+      mode: 0o600,
+    });
     renameSync(tempPath, path);
   } catch (error) {
     try {

package/lib/menu-model.ts

@@ -983,7 +983,7 @@ export function buildModelMenuReplyMarkup(
         callback_data: "model:scope:scoped",
       },
       {
-        text: state.scope === "all" ? "🟡 All" : "⚫️ All",
+        text: state.scope === "all" ? "🟣 All" : "⚫️ All",
         callback_data: "model:scope:all",
       },
     ]);
@@ -1050,7 +1050,7 @@ export function buildModelDetailMenuReplyMarkup(
           callback_data: "model:scope-enable",
         },
         {
-          text: scoped ? "⚫️ All" : "🟡 All",
+          text: scoped ? "⚫️ All" : "🟣 All",
           callback_data: "model:scope-disable",
         },
       ],
@@ -1091,7 +1091,7 @@ export function buildModelPageMenuReplyMarkup(
           return {
             text:
               pageIndex === menuPage.page
-                ? `🟢 ${pageIndex + 1}`
+                ? `🟣 ${pageIndex + 1}`
                 : String(pageIndex + 1),
             callback_data: `model:page:${pageIndex}`,
           };

package/lib/menu-queue.ts

@@ -162,7 +162,7 @@ function buildTelegramQueueItemSubmenuReplyMarkup(
           callback_data: `queue:prio-set:${chatId}:${replyToMessageId}:priority`,
         },
         {
-          text: isPriority ? "⚫️ Normal" : "🟡 Normal",
+          text: isPriority ? "⚫️ Normal" : "🟣 Normal",
           callback_data: `queue:prio-set:${chatId}:${replyToMessageId}:normal`,
         },
       ],

package/lib/menu-settings.ts

@@ -7,7 +7,7 @@
 import {
   getTelegramExtensionSettingsRows,
   type TelegramSectionRegistry,
-} from "./extension-sections.ts";
+} from "./sections.ts";
 import type { TelegramTimeMode } from "./config.ts";
 import type { TelegramInlineKeyboardMarkup } from "./keyboard.ts";
 import type { TelegramModelMenuState } from "./menu-model.ts";
@@ -115,7 +115,8 @@ export interface TelegramSettingsMenuRuntimeDeps<
 
 export const SETTINGS_MENU_TITLE = "<b>⚙️ Settings:</b>";
 export const PROACTIVE_PUSH_SETTINGS_TITLE = "<b>📌 Proactive push:</b>";
-export const TIME_INJECTION_MODE_SETTINGS_TITLE = "<b>🕒 Time injection mode:</b>";
+export const TIME_INJECTION_MODE_SETTINGS_TITLE =
+  "<b>🕒 Time injection mode:</b>";
 export const VOICE_REPLY_MODE_SETTINGS_TITLE = "<b>👄 Voice reply mode:</b>";
 
 type TelegramVoiceReplyModeSetting = TelegramVoiceReplyMode | "hidden";
@@ -124,6 +125,10 @@ function getVoiceReplyModeLabel(mode: TelegramVoiceReplyModeSetting): string {
   return mode;
 }
 
+function getTelegramSettingsStateValueLabel(value: string): string {
+  return value.length > 0 ? value[0]!.toUpperCase() + value.slice(1) : value;
+}
+
 function getVoiceReplyModeSetting(
   mode: TelegramVoiceReplyMode,
   configured: boolean,
@@ -197,21 +202,23 @@ export function buildTelegramSettingsMenuReplyMarkup(
   rows.push(
     [
       {
-        text: `👄 Voice reply: ${getVoiceReplyModeLabel(
-          getVoiceReplyModeSetting(voiceReplyMode, voiceReplyModeConfigured),
+        text: `👄 Voice reply: ${getTelegramSettingsStateValueLabel(
+          getVoiceReplyModeLabel(
+            getVoiceReplyModeSetting(voiceReplyMode, voiceReplyModeConfigured),
+          ),
         )}`,
         callback_data: "settings:open:voice-reply",
       },
     ],
     [
       {
-        text: `🕒 Time injection: ${timeInjectionMode}`,
+        text: `🕒 Time injection: ${getTelegramSettingsStateValueLabel(timeInjectionMode)}`,
         callback_data: "settings:open:time-injection",
       },
     ],
     [
       {
-        text: `📌 Proactive push: ${proactivePushEnabled ? "on" : "off"}`,
+        text: `📌 Proactive push: ${proactivePushEnabled ? "On" : "Off"}`,
         callback_data: "settings:open:proactive",
       },
     ],
@@ -251,11 +258,11 @@ export function buildProactivePushSettingsReplyMarkup(
       [{ text: "⬆️ Back", callback_data: "settings:list" }],
       [
         {
-          text: proactivePushEnabled ? "🟢 on" : "⚫️ on",
+          text: proactivePushEnabled ? "🟢 On" : "⚫️ On",
           callback_data: "settings:set:proactive:on",
         },
         {
-          text: proactivePushEnabled ? "⚫️ off" : "🟡 off",
+          text: proactivePushEnabled ? "⚫️ Off" : "🟡 Off",
           callback_data: "settings:set:proactive:off",
         },
       ],
@@ -372,7 +379,10 @@ export async function handleTelegramSettingsMenuCallbackAction(
     await deps.answerCallbackQuery(callbackQueryId);
     return true;
   }
-  if (data === "settings:open:time-injection" || data === "settings:open:time") {
+  if (
+    data === "settings:open:time-injection" ||
+    data === "settings:open:time"
+  ) {
     await updateTimeInjectionModeSettingsMessage(deps);
     await deps.answerCallbackQuery(callbackQueryId);
     return true;
@@ -506,7 +516,8 @@ export function createTelegramSettingsMenuRuntime<
           ? query.data.slice("settings:set:time-injection:".length)
           : query.data.slice("settings:set:time:".length);
         if (
-          (hasTimeInjectionPrefix || query.data.startsWith("settings:set:time:")) &&
+          (hasTimeInjectionPrefix ||
+            query.data.startsWith("settings:set:time:")) &&
           (timeMode === "off" ||
             timeMode === "hidden" ||
             timeMode === "always" ||

package/lib/menu-status.ts

@@ -8,7 +8,7 @@ import { formatTelegramCommandEmojiPrefix } from "./commands.ts";
 import {
   getTelegramSectionMainMenuRows,
   type TelegramSectionRegistry,
-} from "./extension-sections.ts";
+} from "./sections.ts";
 import {
   formatStatusButtonLabel,
   type TelegramMenuMessageRuntimeDeps,

package/lib/menu.ts

@@ -10,7 +10,7 @@ import {
   handleTelegramSectionSettingsOpen,
   parseTelegramSectionCallback,
   type TelegramSectionRegistry,
-} from "./extension-sections.ts";
+} from "./sections.ts";
 import {
   createTelegramModelMenuStateBuilder,
   handleTelegramModelMenuCallbackAction,