@llblab/pi-telegram 0.13.1 → 0.13.2

package/BACKLOG.md

@@ -1,28 +1,3 @@
 # Project Backlog
 
-## Bound inbound handler output
-
-`Task`: Bound inbound handler stdout, stderr, and recorded failure text before they enter prompts or runtime status.
-
-`Why`: Large OCR, PDF, STT, or failing command output can inflate prompt context, memory use, and `/telegram-status`.
-
-`Exit criteria`:
-
-- Handler stdout added to `[outputs]` is truncated or externalized behind a bounded artifact reference.
-- Handler stderr and stdout included in failure messages are bounded.
-- Runtime event messages and details are bounded before storage and rendering.
-- Regression tests cover large handler stdout and large failure output.
-
-## Recover from invalid config JSON
-
-`Task`: Make `telegram.json` load failures recoverable without bricking pi-telegram session startup.
-
-`Why`: A hand-edited or partially written invalid config currently bubbles `JSON.parse` failure through session start, which can block the normal repair path.
-
-`Exit criteria`:
-
-- Invalid config JSON is reported through a runtime event or clear status diagnostic.
-- Session startup continues with safe empty config defaults.
-- The invalid file is preserved or renamed for operator recovery.
-- `/telegram-setup` remains usable after an invalid config is detected.
-- Regression tests cover invalid config startup behavior.
+No open work.

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 0.13.2: Config Recovery And Inbound Output Bounds Hotfix
+
+- `[Config]` Invalid `telegram.json` now recovers on session startup by renaming the broken file to an `.invalid-*` recovery path, loading safe empty defaults, and recording a runtime diagnostic. Impact: a hand-edited or partially written config no longer bricks `/telegram-setup` or session startup.
+- `[Inbound]` Inbound handler, programmatic handler, voice transcription, and built-in text attachment outputs are now bounded before entering Telegram prompt context. Impact: large OCR, PDF, STT, or text-file outputs cannot silently explode prompt size.
+- `[Diagnostics]` Runtime event messages/details and inbound handler failure stdout/stderr are truncated before storage/rendering. Impact: `/telegram-status` remains useful after noisy provider or handler failures without hiding that truncation happened.
+
 ## 0.13.1: Rendering, Typing, And Continue Queue Hotfix
 
 - `[Rendering]` Fixed Telegram HTML rendering for Markdown bold/italic spans that cross soft line breaks, so assistant replies like `**first line\nsecond line**` render as bold text instead of showing raw asterisks. Added a regression for the guest-mode-style multiline bold reply shape.

package/index.ts

@@ -48,7 +48,15 @@ export default function (pi: Pi.ExtensionAPI) {
   } = piRuntime;
   const bridgeRuntime = Runtime.createTelegramBridgeRuntime();
   const { abort, lifecycle, queue, setup, typing } = bridgeRuntime;
-  const configStore = Config.createTelegramConfigStore();
+  let configStoreForRedaction: Config.TelegramConfigStore | undefined;
+  const runtimeEvents = Status.createTelegramRuntimeEventRecorder({
+    getBotToken() {
+      return configStoreForRedaction?.getBotToken();
+    },
+  });
+  const recordRuntimeEvent = runtimeEvents.record;
+  const configStore = Config.createTelegramConfigStore({ recordRuntimeEvent });
+  configStoreForRedaction = configStore;
   Config.bindGlobalTelegramConfigRuntime(configStore);
   const configControls = Config.createTelegramConfigControls(configStore);
   const lockRuntime = Locks.createTelegramLockRuntime<Pi.ExtensionContext>();
@@ -68,10 +76,6 @@ export default function (pi: Pi.ExtensionAPI) {
   const modelMenuRuntime = Menu.createTelegramModelMenuRuntime<ActivePiModel>();
   const sectionRegistry = Sections.createAndBindTelegramSectionRegistry();
 
-  const runtimeEvents = Status.createTelegramRuntimeEventRecorder({
-    getBotToken: configStore.getBotToken,
-  });
-  const recordRuntimeEvent = runtimeEvents.record;
   const timeInjectionRuntime = TimeInjection.createTimeInjectionRuntime({
     getConfig: Config.createTelegramTimeConfigGetter(configStore),
     recordRuntimeEvent,

package/lib/config.ts

@@ -84,6 +84,17 @@ export interface TelegramConfigStoreOptions {
   initialConfig?: TelegramConfig;
   agentDir?: string;
   configPath?: string;
+  recordRuntimeEvent?: (
+    category: string,
+    error: unknown,
+    details?: Record<string, unknown>,
+  ) => void;
+}
+
+export interface TelegramInvalidConfigRecovery {
+  configPath: string;
+  recoveryPath: string;
+  error: unknown;
 }
 
 export interface TelegramConfigRuntime {
@@ -125,12 +136,26 @@ export function bindGlobalTelegramConfigRuntime(
   });
 }
 
+function getInvalidTelegramConfigRecoveryPath(configPath: string): string {
+  return `${configPath}.invalid-${process.pid}-${Date.now()}`;
+}
+
 export async function readTelegramConfig(
   configPath: string,
+  options: {
+    onInvalidConfig?: (recovery: TelegramInvalidConfigRecovery) => void;
+  } = {},
 ): Promise<TelegramConfig> {
   if (!existsSync(configPath)) return {};
   const content = await readFile(configPath, "utf8");
-  return JSON.parse(content) as TelegramConfig;
+  try {
+    return JSON.parse(content) as TelegramConfig;
+  } catch (error) {
+    const recoveryPath = getInvalidTelegramConfigRecoveryPath(configPath);
+    await rename(configPath, recoveryPath);
+    options.onInvalidConfig?.({ configPath, recoveryPath, error });
+    return {};
+  }
 }
 
 export async function writeTelegramConfig(
@@ -176,7 +201,15 @@ export function createTelegramConfigStore(
       config.allowedUserId = userId;
     },
     load: async () => {
-      config = await readTelegramConfig(configPath);
+      config = await readTelegramConfig(configPath, {
+        onInvalidConfig: (recovery) => {
+          options.recordRuntimeEvent?.("config", recovery.error, {
+            phase: "load",
+            configPath: recovery.configPath,
+            recoveryPath: recovery.recoveryPath,
+          });
+        },
+      });
     },
     persist: async (nextConfig = config) => {
       await writeTelegramConfig(agentDir, configPath, nextConfig);

package/lib/inbound.ts

@@ -19,6 +19,8 @@ import { getTelegramVoiceTranscriptionProviders } from "./voice.ts";
 
 const DEFAULT_INBOUND_HANDLER_TIMEOUT_MS = 120_000;
 const INBOUND_HANDLER_REGISTRY_KEY = "__piTelegramInboundHandlers__";
+const MAX_INBOUND_HANDLER_OUTPUT_LENGTH = 12_000;
+const MAX_INBOUND_HANDLER_FAILURE_STREAM_LENGTH = 4_000;
 
 type TelegramInboundCommandTemplateConfig =
   | string
@@ -187,12 +189,28 @@ export function clearTelegramInboundHandlers(): void {
   getOrCreateInboundHandlerRegistry().handlers.clear();
 }
 
+function truncateTelegramInboundText(text: string, maxLength: number): string {
+  if (text.length <= maxLength) return text;
+  return `${text.slice(0, maxLength).trimEnd()}… [truncated ${text.length - maxLength} chars]`;
+}
+
+function truncateTelegramInboundOutput(text: string): string {
+  return truncateTelegramInboundText(text, MAX_INBOUND_HANDLER_OUTPUT_LENGTH);
+}
+
+function truncateTelegramInboundFailureStream(text: string): string {
+  return truncateTelegramInboundText(
+    text.trimEnd(),
+    MAX_INBOUND_HANDLER_FAILURE_STREAM_LENGTH,
+  );
+}
+
 function normalizeInboundProgrammaticHandlerText(
   result: TelegramInboundProgrammaticHandlerResult,
 ): string | undefined {
   const text = typeof result === "string" ? result : result?.text;
   const normalized = text?.trim();
-  return normalized || undefined;
+  return normalized ? truncateTelegramInboundOutput(normalized) : undefined;
 }
 
 function normalizeStringList(value: string | string[] | undefined): string[] {
@@ -401,8 +419,10 @@ function formatTelegramInboundHandlerFailure(
   const parts = [
     `Inbound handler exited with code ${result.code}${result.killed ? " (killed)" : ""}`,
   ];
-  if (result.stderr.trim()) parts.push(`stderr:\n${result.stderr.trimEnd()}`);
-  if (result.stdout.trim()) parts.push(`stdout:\n${result.stdout.trimEnd()}`);
+  if (result.stderr.trim())
+    parts.push(`stderr:\n${truncateTelegramInboundFailureStream(result.stderr)}`);
+  if (result.stdout.trim())
+    parts.push(`stdout:\n${truncateTelegramInboundFailureStream(result.stdout)}`);
   return parts.join("\n\n");
 }
 
@@ -431,7 +451,7 @@ async function executeTelegramInboundHandlerInvocation(
   });
   if (result.code !== 0)
     throw new Error(formatTelegramInboundHandlerFailure(result));
-  return result.stdout;
+  return truncateTelegramInboundOutput(result.stdout);
 }
 
 function getTelegramInboundHandlerCompositionSteps(
@@ -504,7 +524,7 @@ async function executeTelegramTextHandlerInvocation(
   });
   if (result.code !== 0)
     throw new Error(formatTelegramInboundHandlerFailure(result));
-  return result.stdout;
+  return truncateTelegramInboundOutput(result.stdout);
 }
 
 async function executeTelegramTextHandler(
@@ -633,7 +653,7 @@ async function transcribeTelegramVoiceFileWithProviders(
     try {
       const result = await provider(file, {});
       const text = typeof result === "string" ? result : result?.text;
-      if (text?.trim()) return text.trim();
+      if (text?.trim()) return truncateTelegramInboundOutput(text.trim());
     } catch (error) {
       options.recordRuntimeEvent?.("voice-transcription-provider", error, {
         fileName: file.fileName || basename(file.path),
@@ -656,7 +676,7 @@ async function readBuiltInTelegramTextAttachment(
     return undefined;
   }
   const name = file.fileName || basename(file.path);
-  return `[${name}]\n${normalized}`;
+  return truncateTelegramInboundOutput(`[${name}]\n${normalized}`);
 }
 
 async function executeTelegramInboundHandler(

package/lib/status.ts

@@ -53,6 +53,8 @@ export interface TelegramStatusContext {
 export type TelegramRuntimeEventDetailValue = string | number | boolean | null;
 
 const MAX_RECENT_TELEGRAM_RUNTIME_EVENTS = 10;
+const MAX_TELEGRAM_RUNTIME_EVENT_MESSAGE_LENGTH = 1000;
+const MAX_TELEGRAM_RUNTIME_EVENT_DETAIL_LENGTH = 1000;
 
 export interface TelegramRuntimeEvent {
   at: number;
@@ -164,12 +166,35 @@ export interface TelegramStatusRuntime<
   getStatusLines: () => string[];
 }
 
+function truncateTelegramRuntimeEventText(text: string, maxLength: number): string {
+  if (text.length <= maxLength) return text;
+  return `${text.slice(0, maxLength).trimEnd()}… [truncated ${text.length - maxLength} chars]`;
+}
+
 export function redactTelegramRuntimeMessage(
   message: string,
   botToken: string | undefined,
 ): string {
-  if (!botToken) return message;
-  return message.split(botToken).join("<redacted-token>");
+  const redacted = botToken
+    ? message.split(botToken).join("<redacted-token>")
+    : message;
+  return truncateTelegramRuntimeEventText(
+    redacted,
+    MAX_TELEGRAM_RUNTIME_EVENT_MESSAGE_LENGTH,
+  );
+}
+
+function redactTelegramRuntimeDetail(
+  message: string,
+  botToken: string | undefined,
+): string {
+  const redacted = botToken
+    ? message.split(botToken).join("<redacted-token>")
+    : message;
+  return truncateTelegramRuntimeEventText(
+    redacted,
+    MAX_TELEGRAM_RUNTIME_EVENT_DETAIL_LENGTH,
+  );
 }
 
 function normalizeTelegramRuntimeEventDetails(
@@ -181,7 +206,7 @@ function normalizeTelegramRuntimeEventDetails(
   for (const [key, value] of Object.entries(details)) {
     if (value === undefined) continue;
     if (typeof value === "string") {
-      normalized[key] = redactTelegramRuntimeMessage(value, botToken);
+      normalized[key] = redactTelegramRuntimeDetail(value, botToken);
       continue;
     }
     if (typeof value === "number" || typeof value === "boolean") {
@@ -192,7 +217,7 @@ function normalizeTelegramRuntimeEventDetails(
       normalized[key] = null;
       continue;
     }
-    normalized[key] = redactTelegramRuntimeMessage(String(value), botToken);
+    normalized[key] = redactTelegramRuntimeDetail(String(value), botToken);
   }
   return Object.keys(normalized).length > 0 ? normalized : undefined;
 }

package/package.json

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