@llblab/pi-telegram 0.20.1 → 0.20.3

package/lib/prompts.ts

@@ -6,6 +6,7 @@
 
 import { Type } from "@sinclair/typebox";
 
+import { getTelegramDiagnosticsDisplayPaths } from "./paths.ts";
 import type { BeforeAgentStartEvent, ExtensionAPI } from "./pi.ts";
 import { TELEGRAM_PREFIX } from "./turns.ts";
 
@@ -17,7 +18,9 @@ const TELEGRAM_TURN_SYSTEM_PROMPT_SUFFIX = `
 
 Telegram turn note: If context was compacted or you need the pi-telegram bridge contract, call tool \`telegram_help\`; hidden comments are valid only for explicit \`telegram_voice\` or \`telegram_button\` actions with payload.`;
 
-const TELEGRAM_HELP_TEXT = `--- TELEGRAM BRIDGE HELP ---
+function buildTelegramHelpText(profileName?: string): string {
+  const diagnosticsPaths = getTelegramDiagnosticsDisplayPaths(profileName);
+  return `--- TELEGRAM BRIDGE HELP ---
 
 How to understand Telegram turns:
 - \`[telegram|thread:name|from:user|guest:group]\` marks Telegram origin and attributes.
@@ -60,15 +63,19 @@ Configurable handlers:
 - If command-template config is not enough, build a companion extension through the public pi-telegram APIs; do not import package-private \`lib/*\` paths.
 
 Debugging pi-telegram:
-- Inspect \`~/.pi/agent/tmp/telegram/state.json\` for runtime state, roster, bindings, slots, reservations, and diagnostics.
-- Inspect \`~/.pi/agent/tmp/telegram/logs.jsonl\` for redacted runtime event evidence.
+- Inspect \`${diagnosticsPaths.state}\` for runtime state, roster, bindings, slots, reservations, and diagnostics.
+- Inspect \`${diagnosticsPaths.logs}\` for redacted runtime event evidence.
 - Use terminal \`telegram-status\` for compact human health; use \`telegram-status --debug\` for the full human-readable diagnostic dump.`;
+}
 
-export function getTelegramHelpText(): string {
-  return TELEGRAM_HELP_TEXT;
+export function getTelegramHelpText(profileName?: string): string {
+  return buildTelegramHelpText(profileName);
 }
 
-export function registerTelegramHelpTool(pi: ExtensionAPI): void {
+export function registerTelegramHelpTool(
+  pi: ExtensionAPI,
+  options: { getActiveProfileName?: () => string | undefined } = {},
+): void {
   pi.registerTool({
     name: "telegram_help",
     label: "Telegram Help",
@@ -77,7 +84,12 @@ export function registerTelegramHelpTool(pi: ExtensionAPI): void {
     parameters: Type.Object({}),
     async execute() {
       return {
-        content: [{ type: "text", text: getTelegramHelpText() }],
+        content: [
+          {
+            type: "text",
+            text: getTelegramHelpText(options.getActiveProfileName?.()),
+          },
+        ],
         details: {},
       };
     },

package/lib/setup.ts

@@ -27,6 +27,11 @@ export interface TelegramPollingStartResult {
   message?: string;
 }
 
+export type TelegramSetupCompletion =
+  | { status: "success"; config: TelegramSetupConfig }
+  | { status: "cancelled" | "unavailable" | "busy" | "validation-failed" }
+  | { status: "polling-failed"; config: TelegramSetupConfig };
+
 export interface TelegramSetupDeps {
   hasUI: boolean;
   env: NodeJS.ProcessEnv;
@@ -120,8 +125,8 @@ export function getTelegramBotTokenPromptSpec(
 
 export async function runTelegramSetup(
   deps: TelegramSetupDeps,
-): Promise<TelegramSetupConfig | undefined> {
-  if (!deps.hasUI) return undefined;
+): Promise<TelegramSetupCompletion> {
+  if (!deps.hasUI) return { status: "unavailable" };
   const tokenPrompt = getTelegramBotTokenPromptSpec(
     deps.env,
     deps.config.botToken,
@@ -130,7 +135,7 @@ export async function runTelegramSetup(
     tokenPrompt.method === "editor"
       ? await deps.promptEditor("Telegram bot token", tokenPrompt.value)
       : await deps.promptInput("Telegram bot token", tokenPrompt.value);
-  if (!token) return undefined;
+  if (!token) return { status: "cancelled" };
   const nextConfig: TelegramSetupConfig = {
     ...deps.config,
     botToken: token.trim(),
@@ -141,11 +146,11 @@ export async function runTelegramSetup(
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     deps.notify(`Telegram API check failed: ${message}`, "error");
-    return undefined;
+    return { status: "validation-failed" };
   }
   if (!data.ok || !data.result) {
     deps.notify(data.description || "Invalid Telegram bot token", "error");
-    return undefined;
+    return { status: "validation-failed" };
   }
   nextConfig.botId = data.result.id;
   nextConfig.botUsername = data.result.username;
@@ -158,21 +163,33 @@ export async function runTelegramSetup(
     "Send /start to your bot in Telegram to pair this extension with your account.",
     "info",
   );
-  const startResult = await deps.startPolling();
+  let startResult: unknown;
+  try {
+    startResult = await deps.startPolling();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    deps.notify(`Telegram polling failed: ${message}`, "error");
+    deps.updateStatus();
+    return { status: "polling-failed", config: nextConfig };
+  }
   if (isTelegramPollingStartResult(startResult) && startResult.message) {
     deps.notify(startResult.message, startResult.ok ? "info" : "error");
   }
   deps.updateStatus();
-  return nextConfig;
+  if (isTelegramPollingStartResult(startResult) && !startResult.ok) {
+    return { status: "polling-failed", config: nextConfig };
+  }
+  return { status: "success", config: nextConfig };
 }
 
 export function createTelegramSetupPromptRuntime<
   TContext extends TelegramSetupPromptContext,
 >(deps: TelegramSetupPromptRuntimeDeps<TContext>) {
-  return async (ctx: TContext): Promise<void> => {
-    if (!ctx.hasUI || !deps.setupGuard.start()) return;
+  return async (ctx: TContext): Promise<TelegramSetupCompletion> => {
+    if (!ctx.hasUI) return { status: "unavailable" };
+    if (!deps.setupGuard.start()) return { status: "busy" };
     try {
-      await runTelegramSetup({
+      return await runTelegramSetup({
         hasUI: ctx.hasUI,
         env: deps.env ?? process.env,
         config: deps.getConfig(),

package/lib/status.ts

@@ -1065,6 +1065,13 @@ function buildTelegramBridgeCompactStatusLines(
       : state.activeSourceMessageIds?.length
         ? "active"
         : "idle";
+  const profileSuffix = state.activeProfileName
+    ? `.${state.activeProfileName.replace(/[^a-zA-Z0-9._-]+/g, "_")}`
+    : "";
+  const diagnosticsPaths = {
+    state: `~/.pi/agent/tmp/telegram/state${profileSuffix}.json`,
+    logs: `~/.pi/agent/tmp/telegram/logs${profileSuffix}.jsonl`,
+  };
   return [
     "connection:",
     `- bot: ${formatTelegramBridgeBotStatus(state)}`,
@@ -1094,8 +1101,8 @@ function buildTelegramBridgeCompactStatusLines(
     ...buildTelegramThreadReconciliationLines(state),
     "",
     "diagnostics:",
-    "- state: ~/.pi/agent/tmp/telegram/state.json",
-    "- logs: ~/.pi/agent/tmp/telegram/logs.jsonl",
+    `- state: ${diagnosticsPaths.state}`,
+    `- logs: ${diagnosticsPaths.logs}`,
     "- full dump: /telegram-status --debug",
   ];
 }

package/lib/threads.ts

@@ -133,30 +133,32 @@ function getNextMonotonicSlot(
   nowMs: number,
   lastSlot?: string,
 ): string | undefined {
-  let maxCode = "A".charCodeAt(0) - 1;
-  for (const record of records.values()) {
-    if (!record.slot || !isCurrentThreadRecord(record)) continue;
-    maxCode = Math.max(maxCode, record.slot.charCodeAt(0));
-  }
-  for (const reservation of reservations) {
-    if (
-      reservation.expiresAtMs !== undefined &&
-      reservation.expiresAtMs <= nowMs
-    )
-      continue;
-    if (!reservation.slot) continue;
-    maxCode = Math.max(maxCode, reservation.slot.charCodeAt(0));
-  }
-  for (const provision of pendingProvisions) {
-    if (provision.expiresAtMs !== undefined && provision.expiresAtMs <= nowMs)
-      continue;
-    if (!provision.slot) continue;
-    maxCode = Math.max(maxCode, provision.slot.charCodeAt(0));
-  }
+  let cursorCode: number | undefined;
   if (lastSlot && /^[A-Z]$/.test(lastSlot)) {
-    maxCode = Math.max(maxCode, lastSlot.charCodeAt(0));
+    cursorCode = lastSlot.charCodeAt(0);
+  } else {
+    cursorCode = "A".charCodeAt(0) - 1;
+    for (const record of records.values()) {
+      if (!record.slot || !isCurrentThreadRecord(record)) continue;
+      cursorCode = Math.max(cursorCode, record.slot.charCodeAt(0));
+    }
+    for (const reservation of reservations) {
+      if (
+        reservation.expiresAtMs !== undefined &&
+        reservation.expiresAtMs <= nowMs
+      )
+        continue;
+      if (!reservation.slot) continue;
+      cursorCode = Math.max(cursorCode, reservation.slot.charCodeAt(0));
+    }
+    for (const provision of pendingProvisions) {
+      if (provision.expiresAtMs !== undefined && provision.expiresAtMs <= nowMs)
+        continue;
+      if (!provision.slot) continue;
+      cursorCode = Math.max(cursorCode, provision.slot.charCodeAt(0));
+    }
   }
-  let code = maxCode + 1;
+  let code = cursorCode + 1;
   if (code > "Z".charCodeAt(0)) code = "A".charCodeAt(0);
   for (let attempt = 0; attempt < 26; attempt++) {
     const candidate = String.fromCharCode(code);
@@ -228,6 +230,39 @@ export interface TelegramTopicTargetStore {
   ) => TelegramTopicTargetRecord | undefined;
 }
 
+export function reconcileTelegramFreshAllocationCursor(
+  store: Pick<
+    TelegramTopicTargetStore,
+    "getBotState" | "list" | "setBotState"
+  >,
+  nowMs = Date.now(),
+): boolean {
+  const currentCursor = store.getBotState().lastSlot;
+  const slottedRecords = store
+    .list()
+    .filter((record) => !!record.slot && /^[A-Z]$/.test(record.slot));
+  if (slottedRecords.some((record) => record.slot === currentCursor)) {
+    return false;
+  }
+  const latestLiveRecord = slottedRecords.reduce<
+    TelegramTopicTargetRecord | undefined
+  >((latest, record) => {
+    if (!latest) return record;
+    if (record.createdAtMs !== latest.createdAtMs) {
+      return record.createdAtMs > latest.createdAtMs ? record : latest;
+    }
+    return record.updatedAtMs > latest.updatedAtMs ? record : latest;
+  }, undefined);
+  const nextCursor = latestLiveRecord?.slot;
+  if (nextCursor === currentCursor) return false;
+  store.setBotState({
+    lastSlot: nextCursor,
+    updatedAtMs: nowMs,
+    lastReconcileAction: "live-cursor-realignment",
+  });
+  return true;
+}
+
 export interface TelegramTopicTargetStoreOptions {
   path: string | (() => string);
   getNowMs?: () => number;
@@ -881,9 +916,6 @@ export function createTelegramTopicTargetStore(
 
   const rememberSlot = (slot: string | undefined, nowMs = getNowMs()) => {
     if (!slot || !/^[A-Z]$/.test(slot)) return;
-    const currentCode =
-      botState.lastSlot?.charCodeAt(0) ?? "A".charCodeAt(0) - 1;
-    if (slot.charCodeAt(0) < currentCode) return;
     botState = { ...botState, lastSlot: slot, updatedAtMs: nowMs };
   };
   const rememberIdentity = (record: TelegramTopicTargetRecord) => {
@@ -1151,6 +1183,7 @@ export function createTelegramTopicTargetStore(
     upsert(record) {
       const next = cloneRecord(record);
       const nextOwnerKey = getRecordOwnerKey(next);
+      const previousRecord = records.get(nextOwnerKey);
       if (isCurrentThreadRecord(next)) {
         for (const existing of Array.from(records.values())) {
           const existingOwnerKey = getRecordOwnerKey(existing);
@@ -1180,7 +1213,12 @@ export function createTelegramTopicTargetStore(
         return cloneRecord(next);
       }
       records.set(nextOwnerKey, next);
-      rememberSlot(next.slot, next.updatedAtMs);
+      if (
+        !previousRecord ||
+        !targetMatches(previousRecord.target, next.target)
+      ) {
+        rememberSlot(next.slot, next.updatedAtMs);
+      }
       rememberIdentity(next);
       loaded = true;
       dirty = true;

package/lib/turns.ts

@@ -8,8 +8,6 @@ import { readFile } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
 
 import {
-  appendTelegramForwardContext,
-  appendTelegramReplyContext,
   buildTelegramReplyContextBlock,
   collectTelegramMessageIds,
   downloadTelegramMessageFiles,

package/package.json

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